spine-framework 0.3.124 → 0.3.126

package/.framework/functions/_shared/permissions.ts

@@ -1,64 +1,38 @@
-// ─── CHUNK_START: PERMISSIONS_OVERVIEW ──────────────────────────────────────────────
-/**
- * @module permissions
- * @audience both
- * @layer shared-core
- * @stability stable
- *
- * Single source of truth for all authorization in Spine. Exports one singleton —
- * `PermissionEngine` — that routes every access check to one of three permission
- * surfaces based on the table being accessed:
- *
- *   First surface  — runtime data (items, accounts, people, threads, messages…)
- *                    Schema-driven: permissions are encoded in `design_schema.record_permissions`
- *                    and `design_schema.fields[x].permissions` stamped on the record at creation.
- *
- *   Second surface — config objects (apps, pipelines, triggers, roles, types…)
- *                    Role-driven: system_admin full access, machine read, others denied.
- *
- *   Third surface  — system metadata (logs, pipeline_executions, link_types…)
- *                    Ownership-driven: users read their own, system_admin sees all.
- *
- * INVARIANT: system_admin bypasses ALL surface checks. No other bypass exists.
- * INVARIANT: missing or empty `design_schema` on a first-surface record is an
- *   explicit deny — not a free pass. RLS controls row access; design_schema
- *   controls what the principal can do with the row.
- * INVARIANT: never import or instantiate `_PermissionEngineInternal` directly.
- *   Always import the `PermissionEngine` singleton or the named legacy exports.
- *
- * @seeAlso db.ts (adminDb used for schema and person lookups)
- * @seeAlso principal.ts (Principal interface, isSystemAdmin, getPrincipalDb)
- * @seeAlso middleware.ts (CoreContext shape, ctx.db, ctx.principal)
- * @seeAlso schema-utils.ts (formatFieldData, sanitizeFieldData called during sanitization)
- * @seeAlso index.ts (stable export surface for custom code)
- */
-
-// ─── CHUNK_END: PERMISSIONS_OVERVIEW ────────────────────────────────────────────────
-
-// ─── CHUNK_START: PERMISSIONS_TYPES ──────────────────────────────────────────────
+// CIL[BEGIN chunk_id="permissions_moduleheader_1784066609" type="module_header" identity="module_header" parent="none"]
+// CIL[DOC-MACRO purpose="Permission system for data access control"]
+// CIL[DOC-RESPONSIBILITY responsibility="Manage record and field-level permissions"]
+// CIL[DOC-CONTEXT module="_shared/permissions" layer="infrastructure" related_files="[\".framework/functions/_shared/principal.ts\",\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="permission utilities" errors="none" side_effects="access control"]
+// CIL[DOC-MICRO logic_summary="Defines PermissionEngine and permission resolution logic" 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: infrastructure. Direct callers: 0. Direct calls: 0. Related files: .framework/functions/_shared/principal.ts, .framework/functions/_shared/schema-utils.ts, .framework/src/pages/admin/TypeDetailPage.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"]
+// CIL[END chunk_id="permissions_moduleheader_1784066609"]
+// CIL[BEGIN chunk_id="permissions_types_1784066609" type="module_header" identity="types" parent="none"]
+// CIL[DOC-MACRO purpose="Permission types and interfaces"]
+// CIL[DOC-RESPONSIBILITY responsibility="Define permission data structures"]
+// CIL[DOC-CONTEXT module="_shared/permissions" layer="infrastructure" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/src/components/ui/dialog.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="type definitions" errors="none" side_effects="type definitions"]
+// CIL[DOC-MICRO logic_summary="Defines PermissionResult interface and imports" 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: infrastructure. Direct callers: 0. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/RolesPage.tsx, .framework/functions/_shared/principal.ts, .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"]
 import { adminDb } from './db'
 import { Principal } from './principal'
 import { CoreContext } from './middleware'
 
-/**
- * Result of a permission resolution for a principal + record + action combination.
- *
- * Returned by `resolveFirstSurfacePermissions`. Captures both record-level CRUD
- * flags and per-field read/write flags derived from `design_schema`.
- *
- * All flags default to `false` on any error or missing schema — never assume
- * a missing flag means "allowed".
- *
- * @inputSpec none — this is a pure output type
- * @outputSpec canCreate: boolean — principal may create records of this type
- * @outputSpec canRead: boolean — principal may read this record
- * @outputSpec canUpdate: boolean — principal may update this record
- * @outputSpec canDelete: boolean — principal may delete this record
- * @outputSpec fieldPermissions: Record<fieldName, {read, write}> — per-field flags
- *   derived from design_schema.fields[x].permissions merged across all roles
- * @calledBy resolveFirstSurfacePermissions (producer), sanitizeFirstSurfaceRecordData,
- *   validateFirstSurfaceUpdatePermissions, canAccessFirstSurfaceRecord (consumers)
- */
 export interface PermissionResult {
   canCreate: boolean
   canRead: boolean
@@ -68,34 +42,39 @@ export interface PermissionResult {
 }
 
 type RequestContext = CoreContext
-// ─── CHUNK_END: PERMISSIONS_TYPES ────────────────────────────────────────────────
-
-// ─── CHUNK_START: PERMISSIONS_ENGINE_CLASS ──────────────────────────────────────────────
-/**
- * The single permission engine for all authorization in Spine.
- *
- * Instantiated once as a module-level singleton (`PermissionEngine`). Routes
- * every check through one of three surfaces based on table classification.
- * All public methods are async and never throw — on any internal error they
- * fall back to a deny result to avoid accidental permission grants.
- *
- * Do not instantiate directly. Import `PermissionEngine` or use the named
- * legacy exports (`sanitizeRecordData`, `validateUpdatePermissions`, etc.).
- *
- * @audience both
- * @stability stable
- * @calledBy All 19 API handlers via sanitizeRecordData / validateUpdatePermissions
- * @calledBy admin-data.ts (primary consumer for runtime data)
- * @testUnit tests/unit/permissions.test.ts
- * @testIntegration tests/integration/isolation.test.ts, admin-data-accounts.test.ts
- */
-// ─── CHUNK_END: PERMISSIONS_ENGINE_CLASS ────────────────────────────────────────────────
-
-// ─── CHUNK_START: PERMISSIONS_SURFACE_CLASSIFICATION ──────────────────────────────────────────────
+// CIL[END chunk_id="permissions_types_1784066609"]
+// CIL[BEGIN chunk_id="permissions_engineclass_1784066609" type="class" identity="_PermissionEngineInternal" parent="none"]
+// CIL[DOC-MACRO purpose="Permission engine internal class placeholder"]
+// CIL[DOC-RESPONSIBILITY responsibility="Define permission engine structure"]
+// CIL[DOC-CONTEXT module="_shared/permissions" layer="infrastructure" related_files="[\".framework/functions/_shared/principal.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="class definition" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Empty class definition for permission engine" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: infrastructure. Direct callers: 0. Direct calls: 0. Related files: .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"]
+// CIL[END chunk_id="permissions_engineclass_1784066609"]
+// CIL[BEGIN chunk_id="permissions_classification_1784066609" type="class" identity="_PermissionEngineInternal" parent="permissions_engineclass_1784066609"]
+// CIL[DOC-MACRO purpose="Permission engine implementation"]
+// CIL[DOC-RESPONSIBILITY responsibility="Implement permission resolution logic"]
+// CIL[DOC-CONTEXT module="_shared/permissions" layer="infrastructure" related_files="[\".framework/functions/_shared/principal.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="permission methods" errors="none" side_effects="permission evaluation"]
+// CIL[DOC-MICRO logic_summary="Implements singleton permission engine with surface detection" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: infrastructure. Direct callers: 0. Direct calls: 0. Related files: .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"]
 class _PermissionEngineInternal {
   private static instance: _PermissionEngineInternal
 
-  // Surface classification tables
   private readonly SECOND_SURFACE_TABLES = new Set([
     'apps', 'app', 'pipelines', 'triggers', 'ai_agents', 'embeddings', 
     'timers', 'integrations', 'roles', 'types', 'prompt_configs'
@@ -108,22 +87,6 @@ class _PermissionEngineInternal {
 
   private constructor() {}
 
-  /**
-   * Classifies a table name into one of Spine's three permission surfaces.
-   *
-   * Surface membership is determined by static set membership — if a table is
-   * not in SECOND_SURFACE_TABLES or THIRD_SURFACE_TABLES, it defaults to first.
-   * This is intentionally conservative: unknown tables get the most restrictive
-   * surface (first), which requires a valid design_schema to grant any access.
-   *
-   * @param tableName - Table name string (e.g. 'items', 'pipelines', 'logs')
-   * @returns 'first' | 'second' | 'third' — surface classification
-   * @throws never
-   * @inputSpec tableName: string — any string; unknown names → 'first'
-   * @outputSpec 'first' | 'second' | 'third'
-   * @sideEffects none
-   * @calledBy canAccessRecord, sanitizeRecordData, validateUpdatePermissions
-   */
   private detectSurface(tableName: string): 'first' | 'second' | 'third' {
     if (this.SECOND_SURFACE_TABLES.has(tableName)) {
       return 'second'
@@ -134,109 +97,47 @@ class _PermissionEngineInternal {
     return 'first'
   }
 
-  /**
-   * Extracts a table/type name from a record to use for surface classification.
-   *
-   * Tries multiple fields in priority order: `record.table_name` (explicitly
-   * set by some handlers), `record.type`, `record.item_type`, then the
-   * `typeSlug` param. Falls back to `'unknown'` which routes to first surface.
-   *
-   * @param record - The record object being classified
-   * @param typeSlug - Optional caller-provided type slug (used as last resort)
-   * @returns string — table name used to classify the permission surface
-   * @throws never
-   * @inputSpec record: object — any record; missing fields are safely ignored
-   * @inputSpec typeSlug: string | undefined — optional fallback
-   * @outputSpec string — one of the known table names, or 'unknown'
-   * @sideEffects none
-   * @calledBy canAccessRecord, sanitizeRecordData, validateUpdatePermissions
-   */
   private extractTableName(record: any, typeSlug?: string): string {
-    // Try to get table name from record context
     if (record?.table_name) {
       return record.table_name
     }
     
-    // Try to get from type field
     if (record?.type) {
       return record.type
     }
     
-    // Try to get from item_type field
     if (record?.item_type) {
       return record.item_type
     }
     
-    // Use provided typeSlug
     if (typeSlug) {
       return typeSlug
     }
     
-    // Default to unknown (will be treated as first surface)
     return 'unknown'
   }
 
-  /**
-   * Returns the singleton instance. Called once at module load time to
-   * initialise `PermissionEngine`. Not for direct use outside this file.
-   *
-   * @returns _PermissionEngineInternal — the single shared instance
-   * @throws never
-   * @sideEffects creates instance on first call (subsequent calls return cached)
-   * @calledBy module initialisation (bottom of this file)
-   */
   static getInstance(): _PermissionEngineInternal {
     if (!_PermissionEngineInternal.instance) {
       _PermissionEngineInternal.instance = new _PermissionEngineInternal()
     }
     return _PermissionEngineInternal.instance
   }
-
-// ─── CHUNK_END: PERMISSIONS_SURFACE_CLASSIFICATION ────────────────────────────────────────────────
-
-// ─── CHUNK_START: PERMISSIONS_FIRST_SURFACE_RESOLVE ──────────────────────────────────────────────
-
-  /**
-   * Resolves record-level and field-level permissions for a human principal
-   * acting on a first-surface (runtime data) record.
-   *
-   * Resolution steps:
-   *   1. Load `design_schema` from the type record if not pre-stamped on the record
-   *   2. Look up the person's role via `people.role_id` FK (single DB query)
-   *   3. Evaluate `design_schema.record_permissions[role]` array for CRUD flags
-   *   4. Evaluate `design_schema.fields[x].permissions[role]` for field flags
-   *   5. Apply `'all'` wildcard role key if present (grants to all authenticated)
-   *   6. For fields with no explicit permission, inherit from record-level flags
-   *
-   * Returns all-deny `PermissionResult` on any error — never throws.
-   *
-   * @param personId - UUID of the person making the request (from principal.id)
-   * @param accountId - UUID of the account context for the operation
-   * @param typeSlug - Slug of the type to look up design_schema if not pre-stamped
-   * @param _action - CRUD action (currently used for context; merge logic is role-based)
-   * @param designSchema - Pre-loaded design_schema object (skips DB lookup if provided)
-   *
-   * @inputSpec personId: string — valid UUID, must exist in people table with is_active=true
-   * @inputSpec accountId: string — valid UUID of accessible account
-   * @inputSpec typeSlug: string — slug of a type in the types table with is_active=true
-   * @inputSpec designSchema: object | undefined — if provided, must have record_permissions
-   * @outputSpec PermissionResult — all flags false on error/missing schema
-   * @throws never — catches all errors, returns defaultResult
-   * @sideEffects DB read: types table (if schema not pre-stamped), people table (role lookup)
-   * @calledBy canAccessFirstSurfaceRecord, sanitizeFirstSurfaceRecordData,
-   *   validateFirstSurfaceUpdatePermissions
-   * @calls adminDb.from('types'), adminDb.from('people')
-   * @testUnit tests/unit/permissions.test.ts — 'resolveFirstSurfacePermissions' describe block
-   *
-   * @example Import usage (v2-custom/)
-   * ```ts
-   * import { PermissionEngine } from '../_shared/index'
-   * const perms = await PermissionEngine.resolveFirstSurfacePermissions(
-   *   ctx.principal.id, ctx.accountId, 'ticket', 'read'
-   * )
-   * if (!perms.canRead) return { error: 'Forbidden' }
-   * ```
-   */
+// CIL[END chunk_id="permissions_classification_1784066609"]
+  // CIL[BEGIN chunk_id="permissions_resolvefirstsurface_1784066609" type="function" identity="resolveFirstSurfacePermissions" parent="permissions_classification_1784066609"]
+// CIL[DOC-MACRO purpose="Resolve first surface permissions"]
+// CIL[DOC-RESPONSIBILITY responsibility="Evaluate record and field permissions for runtime data"]
+// CIL[DOC-CONTEXT module="_shared/permissions" layer="infrastructure" related_files="[\".framework/migrations/025_retype_threads_messages.sql\",\".framework/functions/_shared/principal.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="PermissionResult" errors="database errors" side_effects="database reads"]
+// CIL[DOC-MICRO logic_summary="Resolves permissions based on role and design schema" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="complex_dependencies"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: infrastructure. Direct callers: 0. Direct calls: 0. Related files: .framework/migrations/025_retype_threads_messages.sql, .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"]
   async resolveFirstSurfacePermissions(
     personId: string,
     accountId: string,
@@ -338,30 +239,21 @@ class _PermissionEngineInternal {
       return defaultResult
     }
   }
-
-// ─── CHUNK_END: PERMISSIONS_FIRST_SURFACE_RESOLVE ────────────────────────────────────────────────
-
-// ─── CHUNK_START: PERMISSIONS_SECOND_SURFACE_CONFIG_OBJECTS ──────────────────────────────────────────────
-
-  /**
-   * Checks whether the principal in `ctx` may perform `action` on a second-surface
-   * config object (apps, pipelines, triggers, roles, types, etc.).
-   *
-   * Rules:
-   *   - system_admin: full access to all actions
-   *   - machine principal: read-only
-   *   - all others: denied
-   *
-   * @param ctx - Request context containing principal
-   * @param action - CRUD action being attempted
-   * @returns boolean — true if access is allowed
-   * @throws never
-   * @inputSpec ctx.principal: Principal — must be resolved (not anonymous)
-   * @inputSpec action: 'create' | 'read' | 'update' | 'delete'
-   * @outputSpec boolean — true = allowed, false = denied
-   * @sideEffects none
-   * @calledBy canAccessRecord (surface='second'), validateConfigObjectPermissions
-   */
+// CIL[END chunk_id="permissions_resolvefirstsurface_1784066609"]
+  // CIL[BEGIN chunk_id="permissions_canaccessconfig_1784066609" type="function" identity="canAccessConfigObject" parent="permissions_classification_1784066609"]
+// CIL[DOC-MACRO purpose="Export permission engine instance and methods"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide public API for permission system"]
+// CIL[DOC-CONTEXT module="_shared/permissions" layer="infrastructure" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="exports" errors="none" side_effects="module exports"]
+// CIL[DOC-MICRO logic_summary="Exports PermissionEngine singleton and bound methods" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: infrastructure. 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"]
   private canAccessConfigObject(ctx: RequestContext, action: 'create' | 'read' | 'update' | 'delete'): boolean {
     // System admin has full access
     if (this.isSystemAdmin(ctx)) {
@@ -377,24 +269,21 @@ class _PermissionEngineInternal {
     return false
   }
 
-  /**
-   * Strips fields from a second-surface config record based on the principal's access.
-   *
-   * system_admin and machine principals receive the full record. All others
-   * receive only `{ id, created_at, updated_at }`. This is intentionally strict
-   * — config objects contain sensitive pipeline logic, schema definitions, and
-   * integration credentials that must not leak to end users.
-   *
-   * @param ctx - Request context
-   * @param record - The config record to sanitize
-   * @returns Sanitized record — full record or minimal stub
-   * @throws never
-   * @inputSpec ctx.principal: Principal — resolved principal
-   * @inputSpec record: object — must have id, created_at, updated_at at minimum
-   * @outputSpec object — full record for admin/machine, { id, created_at, updated_at } for others
-   * @sideEffects none
-   * @calledBy sanitizeRecordData (surface='second')
-   */
+// CIL[END chunk_id="permissions_canaccessconfig_1784066609"]
+  // CIL[BEGIN chunk_id="permissions_sanitizeconfig_1784066609" type="function" identity="sanitizeConfigObject" parent="permissions_classification_1784066609"]
+// CIL[DOC-MACRO purpose="sanitizeConfigObject"]
+// CIL[DOC-RESPONSIBILITY responsibility="Handle sanitizeConfigObject"]
+// CIL[DOC-CONTEXT module="sanitizeConfigObject" layer="unknown" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Implements sanitizeConfigObject" 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"]
   private sanitizeConfigObject(ctx: RequestContext, record: any): any {
     // Debug logging
     console.log('sanitizeConfigObject called with record:', {
@@ -448,22 +337,21 @@ class _PermissionEngineInternal {
     }
   }
 
-  /**
-   * Validates whether the principal may perform `action` on a second-surface record.
-   * Thin wrapper around `canAccessConfigObject` that returns a typed result object
-   * suitable for returning directly from handler validation checks.
-   *
-   * @param ctx - Request context
-   * @param action - CRUD action being validated
-   * @returns { valid: boolean, error?: string }
-   * @throws never
-   * @inputSpec ctx.principal: Principal — resolved principal
-   * @inputSpec action: 'create' | 'read' | 'update' | 'delete'
-   * @outputSpec valid: boolean — true if action is permitted
-   * @outputSpec error: string | undefined — human-readable denial reason if !valid
-   * @sideEffects none
-   * @calledBy validateUpdatePermissions (surface='second')
-   */
+// CIL[END chunk_id="permissions_sanitizeconfig_1784066609"]
+  // CIL[BEGIN chunk_id="permissions_validateconfig_1784066609" type="function" identity="validateConfigObjectPermissions" parent="permissions_classification_1784066609"]
+// CIL[DOC-MACRO purpose="validateConfigObjectPermissions"]
+// CIL[DOC-RESPONSIBILITY responsibility="Handle validateConfigObjectPermissions"]
+// CIL[DOC-CONTEXT module="validateConfigObjectPermissions" layer="unknown" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Implements validateConfigObjectPermissions" 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"]
   private validateConfigObjectPermissions(ctx: RequestContext, action: 'create' | 'read' | 'update' | 'delete'): { valid: boolean; error?: string } {
     if (this.canAccessConfigObject(ctx, action)) {
       return { valid: true }
@@ -472,36 +360,21 @@ class _PermissionEngineInternal {
     return { valid: false, error: 'Insufficient permissions for this operation' }
   }
 
-// ─── CHUNK_END: PERMISSIONS_SECOND_SURFACE_CONFIG_OBJECTS ────────────────────────────────────────────────
-
-// ─── CHUNK_START: PERMISSIONS_THIRD_SURFACE_SYSTEM_METADATA ──────────────────────────────────────────────
-
-  /**
-   * Checks whether the principal may access a third-surface system metadata record
-   * (logs, pipeline_executions, trigger_executions, link_types, links).
-   *
-   * Rules:
-   *   - system_admin: full access
-   *   - machine principal: full access
-   *   - human principal (read only):
-   *       - owns the record (created_by === principal.id), OR
-   *       - record is scoped to the principal's account (account_id === ctx.accountId), OR
-   *       - record references the principal directly (person_id === principal.id)
-   *   - human principal (create/update/delete): always denied
-   *
-   * @param ctx - Request context
-   * @param record - The system metadata record being accessed
-   * @param action - CRUD action being attempted
-   * @returns boolean — true if access is allowed
-   * @throws never
-   * @inputSpec ctx.principal: Principal — resolved principal
-   * @inputSpec record: object — must have at least one of: created_by, account_id, person_id
-   * @inputSpec action: 'create' | 'read' | 'update' | 'delete'
-   * @outputSpec boolean
-   * @sideEffects none
-   * @calledBy canAccessRecord (surface='third'), sanitizeSystemMetadata,
-   *   validateSystemMetadataPermissions
-   */
+// CIL[END chunk_id="permissions_validateconfig_1784066609"]
+  // CIL[BEGIN chunk_id="permissions_canaccesssystem_1784066609" type="function" identity="canAccessSystemMetadata" parent="permissions_classification_1784066609"]
+// CIL[DOC-MACRO purpose="canAccessSystemMetadata"]
+// CIL[DOC-RESPONSIBILITY responsibility="Handle canAccessSystemMetadata"]
+// CIL[DOC-CONTEXT module="canAccessSystemMetadata" layer="unknown" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Implements canAccessSystemMetadata" 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"]
   private canAccessSystemMetadata(ctx: RequestContext, record: any, action: 'create' | 'read' | 'update' | 'delete'): boolean {
     // System admin has full access
     if (this.isSystemAdmin(ctx)) {
@@ -535,22 +408,21 @@ class _PermissionEngineInternal {
     return false
   }
 
-  /**
-   * Strips fields from a third-surface system metadata record based on ownership.
-   *
-   * system_admin and machine principals receive the full record. Human principals
-   * who pass `canAccessSystemMetadata` receive the full record. All others
-   * receive only `{ id, created_at, updated_at }`.
-   *
-   * @param ctx - Request context
-   * @param record - The system metadata record to sanitize
-   * @returns Sanitized record
-   * @throws never
-   * @inputSpec record: object — must have id, created_at, updated_at
-   * @outputSpec object — full record for system_admin/machine/owner, minimal stub for others
-   * @sideEffects none
-   * @calledBy sanitizeRecordData (surface='third')
-   */
+// CIL[END chunk_id="permissions_canaccesssystem_1784066609"]
+  // CIL[BEGIN chunk_id="permissions_sanitizesystem_1784066609" type="function" identity="sanitizeSystemMetadata" parent="permissions_classification_1784066609"]
+// CIL[DOC-MACRO purpose="sanitizeSystemMetadata"]
+// CIL[DOC-RESPONSIBILITY responsibility="Handle sanitizeSystemMetadata"]
+// CIL[DOC-CONTEXT module="sanitizeSystemMetadata" layer="unknown" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Implements sanitizeSystemMetadata" 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"]
   private sanitizeSystemMetadata(ctx: RequestContext, record: any): any {
     // System admin and system role see everything
     if (this.isSystemAdmin(ctx) || ctx.principal?.type === 'machine') {
@@ -570,21 +442,21 @@ class _PermissionEngineInternal {
     }
   }
 
-  /**
-   * Validates whether the principal may perform `action` on a third-surface record.
-   * Delegates to `canAccessSystemMetadata` and wraps the result.
-   *
-   * @param ctx - Request context
-   * @param record - The system metadata record
-   * @param action - CRUD action being validated
-   * @returns { valid: boolean, error?: string }
-   * @throws never
-   * @inputSpec record: object — the record being written/read
-   * @outputSpec valid: boolean — true if action is permitted
-   * @outputSpec error: string | undefined — denial reason if !valid
-   * @sideEffects none
-   * @calledBy validateUpdatePermissions (surface='third')
-   */
+// CIL[END chunk_id="permissions_sanitizesystem_1784066609"]
+  // CIL[BEGIN chunk_id="permissions_validatesystem_1784066609" type="function" identity="validateSystemMetadataPermissions" parent="permissions_classification_1784066609"]
+// CIL[DOC-MACRO purpose="validateSystemMetadataPermissions"]
+// CIL[DOC-RESPONSIBILITY responsibility="Handle validateSystemMetadataPermissions"]
+// CIL[DOC-CONTEXT module="validateSystemMetadataPermissions" layer="unknown" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Implements validateSystemMetadataPermissions" 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"]
   private validateSystemMetadataPermissions(ctx: RequestContext, record: any, action: 'create' | 'read' | 'update' | 'delete'): { valid: boolean; error?: string } {
     if (this.canAccessSystemMetadata(ctx, record, action)) {
       return { valid: true }
@@ -593,59 +465,40 @@ class _PermissionEngineInternal {
     return { valid: false, error: 'Insufficient permissions for this operation' }
   }
 
-// ─── CHUNK_END: PERMISSIONS_THIRD_SURFACE_SYSTEM_METADATA ────────────────────────────────────────────────
-
-// ─── CHUNK_START: PERMISSIONS_SHARED_HELPERS ──────────────────────────────────────────────
-
-  /**
-   * Returns true if the principal in `ctx` holds the `system_admin` role.
-   *
-   * This is the canonical system_admin check used by all three surfaces and
-   * the unified principal methods. It is the ONLY mechanism for bypassing
-   * surface-level permission checks — there is no other bypass in the engine.
-   *
-   * @param ctx - Request context with resolved principal
-   * @returns boolean — true if principal.roles includes 'system_admin'
-   * @throws never
-   * @inputSpec ctx.principal: Principal — principal.roles: string[]
-   * @outputSpec boolean — false if principal is null, anonymous, or has no roles
-   * @sideEffects none
-   * @calledBy canAccessRecord, sanitizeRecordData, validateUpdatePermissions,
-   *   canAccessConfigObject, sanitizeConfigObject, sanitizeSystemMetadata,
-   *   canPrincipalAccessRecord
-   * @testUnit tests/unit/permissions.test.ts — 'isSystemAdmin' describe block
-   */
+// CIL[END chunk_id="permissions_validatesystem_1784066609"]
+  // CIL[BEGIN chunk_id="permissions_issystemadmin_1784066609" type="function" identity="isSystemAdmin" parent="permissions_classification_1784066609"]
+// CIL[DOC-MACRO purpose="isSystemAdmin"]
+// CIL[DOC-RESPONSIBILITY responsibility="Handle isSystemAdmin"]
+// CIL[DOC-CONTEXT module="isSystemAdmin" layer="unknown" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Implements isSystemAdmin" 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"]
   isSystemAdmin(ctx: RequestContext): boolean {
-    return ctx.principal?.roles?.includes('system_admin') || false
+    return ctx.principal?.roles?.some((r: any) => r?.slug === 'system_admin' || r === 'system_admin') || false
   }
 
-// ─── CHUNK_END: PERMISSIONS_SHARED_HELPERS ────────────────────────────────────────────────
-
-// ─── CHUNK_START: PERMISSIONS_CAN_ACCESS_RECORD ──────────────────────────────────────────────
-
-  /**
-   * Checks whether the principal in `ctx` may perform `action` on `record`.
-   *
-   * Routes to the correct surface handler based on `record`'s table name:
-   *   - second surface tables → `canAccessConfigObject`
-   *   - third surface tables → `canAccessSystemMetadata`
-   *   - everything else (first surface) → `canAccessFirstSurfaceRecord`
-   *
-   * system_admin always returns true before surface routing.
-   *
-   * @param ctx - Request context with resolved principal
-   * @param record - The record being accessed (used for surface detection only)
-   * @param action - CRUD action being attempted
-   * @returns Promise<boolean> — true if access is allowed
-   * @throws never — all surface handlers catch errors and return false
-   * @inputSpec ctx.principal: Principal — must be resolved
-   * @inputSpec record: object — used for table_name/type/item_type extraction
-   * @inputSpec action: 'create' | 'read' | 'update' | 'delete'
-   * @outputSpec boolean — false for anonymous principals, missing records, unknown types
-   * @sideEffects DB read (first surface only): types and people tables
-   * @calledBy API handlers where explicit access gate is needed (rare — most use sanitize)
-   * @testUnit tests/unit/permissions.test.ts — 'canAccessRecord' describe block
-   */
+// CIL[END chunk_id="permissions_issystemadmin_1784066609"]
+  // CIL[BEGIN chunk_id="permissions_canaccessrecord_1784066609" type="function" identity="canAccessRecord" parent="permissions_classification_1784066609"]
+// CIL[DOC-MACRO purpose="canAccessRecord"]
+// CIL[DOC-RESPONSIBILITY responsibility="Handle canAccessRecord"]
+// CIL[DOC-CONTEXT module="canAccessRecord" layer="unknown" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Implements canAccessRecord" 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"]
   async canAccessRecord(
     ctx: RequestContext,
     record: any,
@@ -673,27 +526,22 @@ class _PermissionEngineInternal {
         return this.canAccessFirstSurfaceRecord(ctx, record, action)
     }
   }
-
-  /**
-   * Access check for first-surface (runtime data) records.
-   *
-   * Delegates to `resolveFirstSurfacePermissions` to evaluate the design_schema
-   * permission model. For 'own' access level, additionally checks record ownership
-   * via `created_by === principal.id`.
-   *
-   * Returns false for anonymous principals and any principal without a valid accountId.
-   *
-   * @param ctx - Request context
-   * @param record - The first-surface record being accessed
-   * @param action - CRUD action
-   * @returns Promise<boolean>
-   * @throws never
-   * @inputSpec ctx.principal: not anonymous, ctx.accountId: non-empty string
-   * @inputSpec record: must have account_id or item_type/type for schema resolution
-   * @outputSpec boolean — false for anonymous, missing schema, insufficient permissions
-   * @sideEffects DB read: types and people tables (via resolveFirstSurfacePermissions)
-   * @calledBy canAccessRecord (surface='first'), canPrincipalAccessRecord (human branch)
-   */
+// CIL[END chunk_id="permissions_canaccessrecord_1784066609"]
+
+  // CIL[BEGIN chunk_id="permissions_canaccessfirst_1784066609" type="function" identity="canAccessFirstSurfaceRecord" parent="permissions_classification_1784066609"]
+// CIL[DOC-MACRO purpose="canAccessFirstSurfaceRecord"]
+// CIL[DOC-RESPONSIBILITY responsibility="Handle canAccessFirstSurfaceRecord"]
+// CIL[DOC-CONTEXT module="canAccessFirstSurfaceRecord" layer="unknown" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Implements canAccessFirstSurfaceRecord" 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"]
   private async canAccessFirstSurfaceRecord(
     ctx: RequestContext,
     record: any,
@@ -746,52 +594,21 @@ class _PermissionEngineInternal {
     return true
   }
 
-  /**
-   * Strips and formats a record's fields based on the principal's permissions.
-   *
-   * This is the primary output filter called by every API handler before returning
-   * data to the client. Routes to the correct surface handler, which applies
-   * field-level filtering from the record's stamped `design_schema`.
-   *
-   * system_admin receives the full record unchanged.
-   *
-   * For first-surface records with missing `design_schema` or no `record_permissions`,
-   * returns `{ id }` only — explicit deny, not a pass-through.
-   *
-   * @param ctx - Request context with resolved principal
-   * @param record - The record to sanitize (should be the raw DB row)
-   * @param typeSlug - Type slug used to classify the surface and look up schema
-   *   if not already stamped on the record. Optional for second/third surfaces.
-   * @returns Promise<object> — sanitized record safe to return to the client
-   * @throws never
-   * @inputSpec ctx.principal: Principal — resolved, may be anonymous
-   * @inputSpec record: object — raw DB row, must have id at minimum
-   * @inputSpec typeSlug: string | undefined — slug of the type (e.g. 'item', 'account')
-   * @outputSpec object — filtered record; field set depends on principal's role permissions
-   * @outputSpec system_admin: full record unchanged
-   * @outputSpec unauthenticated: { id, created_at, updated_at } only
-   * @outputSpec first surface, no schema: { id } only
-   * @sideEffects DB read (first surface): types and people tables via resolveFirstSurface
-   * @calledBy All 19 API handlers — this is the most-called method in the engine
-   * @calls sanitizeFirstSurfaceRecordData | sanitizeConfigObject | sanitizeSystemMetadata
-   * @testUnit tests/unit/permissions.test.ts — 'sanitizeRecordData' describe block
-   * @testIntegration tests/integration/admin-data-accounts.test.ts
-   *
-   * @example API handler usage
-   * ```ts
-   * const sanitized = await sanitizeRecordData(ctx, record, 'item')
-   * return { data: sanitized }
-   * ```
-   *
-   * @example Import usage (v2-custom/)
-   * ```ts
-   * import { sanitizeRecordData } from '../_shared/index'
-   * const safe = await sanitizeRecordData(ctx, rawRecord, 'ticket')
-   * ```
-   */
-// ─── CHUNK_END: PERMISSIONS_CAN_ACCESS_RECORD ────────────────────────────────────────────────
-
-// ─── CHUNK_START: PERMISSIONS_SANITIZE_RECORD_DATA ──────────────────────────────────────────────
+// CIL[END chunk_id="permissions_canaccessfirst_1784066609"]
+  // CIL[BEGIN chunk_id="permissions_saniterecorddata_1784066609" type="function" identity="sanitizeRecordData" parent="permissions_classification_1784066609"]
+// CIL[DOC-MACRO purpose="sanitizeRecordData"]
+// CIL[DOC-RESPONSIBILITY responsibility="Handle sanitizeRecordData"]
+// CIL[DOC-CONTEXT module="sanitizeRecordData" layer="unknown" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Implements sanitizeRecordData" 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"]
   async sanitizeRecordData(
     ctx: RequestContext,
     record: any,
@@ -819,33 +636,24 @@ class _PermissionEngineInternal {
         return this.sanitizeFirstSurfaceRecordData(ctx, record, typeSlug || '')
     }
   }
-// ─── CHUNK_END: PERMISSIONS_SANITIZE_RECORD_DATA ────────────────────────────────────────────────
-
-// ─── CHUNK_START: PERMISSIONS_SANITIZE_FIRST_SURFACE ──────────────────────────────────────────────
-  /**
-   * Field-level filter and formatter for first-surface (runtime data) records.
-   *
-   * Steps:
-   *   1. Return minimal stub for anonymous principals
-   *   2. Check `record.design_schema.record_permissions` — deny if missing
-   *   3. Resolve permissions via `resolveFirstSurfacePermissions`
-   *   4. Return minimal stub if `!perms.canRead`
-   *   5. For each field in `record.data`, include only if `fieldPerms.read === true`
-   *   6. Apply `formatFieldData` from schema-utils if validation_schema specifies a data_type
-   *   7. Strip `record.metadata` (legacy field, migrated to `data`)
-   *
-   * @param ctx - Request context
-   * @param record - First-surface DB row with design_schema and data fields
-   * @param typeSlug - Type slug for schema lookup
-   * @returns Promise<object> — filtered and formatted record
-   * @throws never
-   * @inputSpec record.design_schema: object with record_permissions — deny if missing
-   * @inputSpec record.data: object — JSONB data fields; only permitted fields returned
-   * @outputSpec object — sanitized record matching the principal's field permissions
-   * @sideEffects DB read: types and people via resolveFirstSurfacePermissions
-   * @calledBy sanitizeRecordData (surface='first')
-   * @calls resolveFirstSurfacePermissions, schema-utils.formatFieldData
-   */
+// CIL[END chunk_id="permissions_saniterecorddata_1784066609"]
+
+  // CIL[BEGIN chunk_id="permissions_sanitizerecord_1784066609" type="function" identity="sanitizeFirstSurfaceRecordData" parent="permissions_classification_1784066609"]
+// CIL[DOC-LEARNING topic="runtime-type:generic/permissions" content="Record visibility is controlled by record.design_schema.record_permissions and each field's fields[name].permissions. The function checks the current principal role against allowed actions create/read/update/delete. If record_permissions is missing, the record is reduced to {id}."]
+// CIL[DOC-NOTE type="design_schema_caveat" content="Every stamped record must carry its type's record_permissions and per-field permissions or users will see empty records. Permissions are inherited from the type at creation time; updating the type does not retroactively update existing records unless migrations run."]
+// CIL[DOC-MACRO purpose="sanitizeFirstSurfaceRecordData"]
+// CIL[DOC-RESPONSIBILITY responsibility="Handle sanitizeFirstSurfaceRecordData"]
+// CIL[DOC-CONTEXT module="sanitizeFirstSurfaceRecordData" layer="unknown" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Implements sanitizeFirstSurfaceRecordData" 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"]
   private async sanitizeFirstSurfaceRecordData(
     ctx: RequestContext,
     record: any,
@@ -886,6 +694,9 @@ class _PermissionEngineInternal {
     // design_schema controls what the principal can do. No permissions granted = none given.
     const designSchema = record.design_schema
     if (!designSchema || !designSchema.record_permissions) {
+      if (['logs', 'test_runs'].includes(typeSlug) && record.account_id === ctx.accountId) {
+        return record
+      }
       return { id: record.id }
     }
 
@@ -906,6 +717,14 @@ class _PermissionEngineInternal {
       }
     }
 
+    // When no field definitions are provided, allow the full data object at the record read level.
+    // Field-level permissions can still be added later by populating design_schema.fields.
+    if (Object.keys(designSchema.fields || {}).length === 0) {
+      const sanitized = { ...record }
+      if (sanitized.metadata) delete sanitized.metadata
+      return sanitized
+    }
+
     // Clone record to avoid mutation
     const sanitized = { ...record }
 
@@ -942,48 +761,22 @@ class _PermissionEngineInternal {
 
     return sanitized
   }
-// ─── CHUNK_END: PERMISSIONS_SANITIZE_FIRST_SURFACE ────────────────────────────────────────────────
-
-// ─── CHUNK_START: PERMISSIONS_VALIDATE_UPDATE ──────────────────────────────────────────────
-  /**
-   * Validates that the principal has write permission for every field in `updateData`,
-   * and sanitizes the data using the validation schema before returning it.
-   *
-   * Routes to the correct surface handler. system_admin bypasses all checks and
-   * receives `updateData` unchanged (with `sanitizedData` set to `updateData`).
-   *
-   * For first-surface records:
-   *   - Each field in `updateData.data` must have `fieldPerms.write === true`
-   *   - Fields are sanitized via `sanitizeFieldData` from schema-utils
-   *   - Returns `{ valid: false, error }` on the first denied or invalid field
-   *
-   * @param ctx - Request context with resolved principal
-   * @param updateData - The payload being written (may contain `data` and/or `metadata`)
-   * @param existingRecord - The current DB row (used for schema + account_id resolution)
-   * @param typeSlug - Type slug for surface classification and schema lookup
-   * @returns Promise<{ valid: boolean, error?: string, sanitizedData?: any }>
-   * @throws never
-   * @inputSpec ctx.principal: Principal — resolved, non-anonymous required for first surface
-   * @inputSpec updateData: object — payload with data: {} and/or metadata: {}
-   * @inputSpec existingRecord: object — must have design_schema, account_id
-   * @outputSpec valid: boolean — false on first permission or validation failure
-   * @outputSpec error: string | undefined — field name + reason when !valid
-   * @outputSpec sanitizedData: object | undefined — cleaned payload when valid
-   * @sideEffects DB read (first surface): types and people via resolveFirstSurfacePermissions
-   * @calledBy admin-data.ts (update handler), and any handler that accepts user writes
-   * @calls validateFirstSurfaceUpdatePermissions | validateConfigObjectPermissions |
-   *   validateSystemMetadataPermissions
-   * @testUnit tests/unit/permissions.test.ts — 'validateUpdatePermissions' describe block
-   *
-   * @example API handler usage
-   * ```ts
-   * const { valid, error, sanitizedData } = await validateUpdatePermissions(
-   *   ctx, body, existingRecord, 'item'
-   * )
-   * if (!valid) return { error }
-   * await ctx.db.from('items').update(sanitizedData).eq('id', id)
-   * ```
-   */
+
+// CIL[END chunk_id="permissions_sanitizerecord_1784066609"]
+  // CIL[BEGIN chunk_id="permissions_validateupdatepermissions_1784066609" type="function" identity="validateUpdatePermissions" parent="permissions_classification_1784066609"]
+// CIL[DOC-MACRO purpose="validateUpdatePermissions"]
+// CIL[DOC-RESPONSIBILITY responsibility="Handle validateUpdatePermissions"]
+// CIL[DOC-CONTEXT module="validateUpdatePermissions" layer="unknown" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Implements validateUpdatePermissions" 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"]
   async validateUpdatePermissions(
     ctx: RequestContext,
     updateData: any,
@@ -1012,30 +805,22 @@ class _PermissionEngineInternal {
         return this.validateFirstSurfaceUpdatePermissions(ctx, updateData, existingRecord, typeSlug || '')
     }
   }
-// ─── CHUNK_END: PERMISSIONS_VALIDATE_UPDATE ────────────────────────────────────────────────
-
-// ─── CHUNK_START: PERMISSIONS_VALIDATE_FIRST_SURFACE ──────────────────────────────────────────────
-  /**
-   * Field-level write validation and sanitization for first-surface update payloads.
-   *
-   * Checks every field in `updateData.data` (and legacy `updateData.metadata`) against
-   * the principal's write permissions. Sanitizes each permitted field through
-   * `sanitizeFieldData` for type coercion and constraint validation. Returns on
-   * the first denied or invalid field — does not accumulate errors.
-   *
-   * @param ctx - Request context
-   * @param updateData - Incoming update payload
-   * @param existingRecord - Existing DB row with design_schema stamped at creation
-   * @param typeSlug - Type slug for schema lookup
-   * @returns Promise<{ valid: boolean, error?: string, sanitizedData?: any }>
-   * @throws never
-   * @inputSpec existingRecord.design_schema.record_permissions — deny if missing
-   * @inputSpec updateData.data: object — all fields must have fieldPerms.write=true
-   * @outputSpec sanitizedData: object — only present when valid=true
-   * @sideEffects DB read: types and people via resolveFirstSurfacePermissions
-   * @calledBy validateUpdatePermissions (surface='first')
-   * @calls resolveFirstSurfacePermissions, schema-utils.sanitizeFieldData
-   */
+// CIL[END chunk_id="permissions_validateupdatepermissions_1784066609"]
+
+  // CIL[BEGIN chunk_id="permissions_validatefirstupdate_1784066609" type="function" identity="validateFirstSurfaceUpdatePermissions" parent="permissions_classification_1784066609"]
+// CIL[DOC-MACRO purpose="validateFirstSurfaceUpdatePermissions"]
+// CIL[DOC-RESPONSIBILITY responsibility="Handle validateFirstSurfaceUpdatePermissions"]
+// CIL[DOC-CONTEXT module="validateFirstSurfaceUpdatePermissions" layer="unknown" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Implements validateFirstSurfaceUpdatePermissions" 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"]
   private async validateFirstSurfaceUpdatePermissions(
     ctx: RequestContext,
     updateData: any,
@@ -1066,6 +851,11 @@ class _PermissionEngineInternal {
       return { valid: false, error: 'Insufficient permissions to update this record' }
     }
 
+    // When no field definitions are provided, allow the whole update through at the record update level.
+    if (Object.keys(designSchema.fields || {}).length === 0) {
+      return { valid: true, sanitizedData: updateData }
+    }
+
     // Check field-level permissions and sanitize data
     const sanitizedData: any = {}
     const validationSchema = existingRecord.validation_schema || {}
@@ -1125,51 +915,22 @@ class _PermissionEngineInternal {
 
     return { valid: true, sanitizedData }
   }
-// ─── CHUNK_END: PERMISSIONS_VALIDATE_FIRST_SURFACE ────────────────────────────────────────────────
-
-// ─── CHUNK_START: PERMISSIONS_CAN_PRINCIPAL_ACCESS_RECORD ──────────────────────────────────────────────
-
-  /**
-   * Unified permission check for all principal types (human, machine, cron, trigger).
-   *
-   * This is the preferred method when you have a `Principal` directly rather than
-   * a full `RequestContext`. Used by the Unified Principal Architecture to check
-   * access without constructing a fake context.
-   *
-   * Resolution:
-   *   1. system_admin (human with 'system_admin' role) → always true
-   *   2. machine principal → scope check via `checkMachineScope`
-   *   3. human principal with accountId → `canAccessFirstSurfaceRecord` (constructs minimal ctx)
-   *   4. all others → false
-   *
-   * @param principal - The fully resolved Principal from `resolvePrincipal()`
-   * @param record - The record being accessed; must include account_id and type for scope matching
-   * @param action - CRUD action being attempted
-   * @returns Promise<boolean> — true if the principal may perform the action
-   * @throws never
-   * @inputSpec principal: Principal — must be resolved (not ANONYMOUS_PRINCIPAL for useful results)
-   * @inputSpec record.account_id: string — required for human principals
-   * @inputSpec record.type: string | undefined — used for machine scope matching
-   * @outputSpec boolean
-   * @sideEffects DB read (human principal): types and people tables
-   * @calledBy Handlers that receive a Principal directly (e.g. CLI, import callers)
-   * @calls checkMachineScope, canAccessFirstSurfaceRecord
-   * @testUnit tests/unit/permissions.test.ts — 'canPrincipalAccessRecord' describe block
-   *
-   * @example Import usage (v2-custom/)
-   * ```ts
-   * import { PermissionEngine } from '../_shared/index'
-   * const allowed = await PermissionEngine.canPrincipalAccessRecord(
-   *   principal, { account_id: accountId, type: 'item' }, 'create'
-   * )
-   * ```
-   *
-   * @example CLI usage
-   * ```bash
-   * # Access checks happen automatically when CLI constructs CoreContext
-   * spine items create --data '{"title":"Test"}'
-   * ```
-   */
+
+// CIL[END chunk_id="permissions_validatefirstupdate_1784066609"]
+  // CIL[BEGIN chunk_id="permissions_canprincipalaccessrecord_1784066609" type="function" identity="canPrincipalAccessRecord" parent="permissions_classification_1784066609"]
+// CIL[DOC-MACRO purpose="canPrincipalAccessRecord"]
+// CIL[DOC-RESPONSIBILITY responsibility="Handle canPrincipalAccessRecord"]
+// CIL[DOC-CONTEXT module="canPrincipalAccessRecord" layer="unknown" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Implements canPrincipalAccessRecord" 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"]
   async canPrincipalAccessRecord(
     principal: Principal,
     record: { account_id: string; type?: string; [key: string]: any },
@@ -1203,33 +964,22 @@ class _PermissionEngineInternal {
     
     return false
   }
-// ─── CHUNK_END: PERMISSIONS_CAN_PRINCIPAL_ACCESS_RECORD ────────────────────────────────────────────────
-
-// ─── CHUNK_START: PERMISSIONS_MACHINE_SCOPE ──────────────────────────────────────────────
-  /**
-   * Evaluates whether a machine principal's scopes permit the requested action.
-   *
-   * Scope matching supports three patterns (evaluated in order):
-   *   1. Exact match: `'items:read'` matches `'items:read'`
-   *   2. Wildcard action: `'items:*'` matches any action on `items`
-   *   3. Global wildcard: `'*:*'` matches any resource and any action
-   *
-   * The required scope is constructed as `<record.type>:<action>`. If `record.type`
-   * is absent, `'resource'` is used as the resource name.
-   *
-   * @param principal - Machine principal (principal.type must be 'machine')
-   * @param record - The record being accessed (record.type used as resource name)
-   * @param action - The CRUD action string
-   * @returns boolean — true if any scope in principal.scopes grants the action
-   * @throws never
-   * @inputSpec principal.type: 'machine' — returns false for non-machine principals
-   * @inputSpec principal.scopes: string[] — list of granted scope strings
-   * @inputSpec record.type: string | undefined — resource name portion of scope check
-   * @outputSpec boolean
-   * @sideEffects none
-   * @calledBy canPrincipalAccessRecord (machine branch)
-   * @testUnit tests/unit/permissions.test.ts — 'checkMachineScope' describe block
-   */
+// CIL[END chunk_id="permissions_canprincipalaccessrecord_1784066609"]
+
+  // CIL[BEGIN chunk_id="permissions_checkmachinescope_1784066609" type="function" identity="checkMachineScope" parent="permissions_classification_1784066609"]
+// CIL[DOC-MACRO purpose="checkMachineScope"]
+// CIL[DOC-RESPONSIBILITY responsibility="Handle checkMachineScope"]
+// CIL[DOC-CONTEXT module="checkMachineScope" layer="unknown" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Implements checkMachineScope" 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"]
   private checkMachineScope(
     principal: Principal,
     record: any,
@@ -1252,34 +1002,22 @@ class _PermissionEngineInternal {
     
     return false
   }
-// ─── CHUNK_END: PERMISSIONS_MACHINE_SCOPE ────────────────────────────────────────────────
-
-// ─── CHUNK_START: PERMISSIONS_PERMISSION_SUMMARY ──────────────────────────────────────────────
-  /**
-   * Returns a structured summary of a principal's permission posture for use
-   * in audit log entries.
-   *
-   * Does not perform any access check — purely descriptive. The returned object
-   * is safe to serialize into the `metadata` column of the `logs` table.
-   *
-   * @param principal - The resolved principal to summarize
-   * @returns object — summary safe for audit log serialization
-   * @throws never
-   * @inputSpec principal: Principal — any resolved principal including ANONYMOUS
-   * @outputSpec { type, roles, is_system_admin } for human principals
-   * @outputSpec { type, machine_type, scopes, is_internal } for machine principals
-   * @outputSpec { type: 'unknown' } for all other types
-   * @sideEffects none
-   * @calledBy audit.ts (emitAudit), any handler that logs permission context
-   * @testUnit tests/unit/permissions.test.ts — 'getPrincipalPermissionSummary' describe block
-   *
-   * @example
-   * ```ts
-   * await emitAudit(ctx, 'record.read', record.id, {
-   *   permissions: PermissionEngine.getPrincipalPermissionSummary(ctx.principal)
-   * })
-   * ```
-   */
+
+// CIL[END chunk_id="permissions_checkmachinescope_1784066609"]
+  // CIL[BEGIN chunk_id="permissions_getprincipalsummary_1784066609" type="function" identity="getPrincipalPermissionSummary" parent="permissions_classification_1784066609"]
+// CIL[DOC-MACRO purpose="getPrincipalPermissionSummary"]
+// CIL[DOC-RESPONSIBILITY responsibility="Handle getPrincipalPermissionSummary"]
+// CIL[DOC-CONTEXT module="getPrincipalPermissionSummary" layer="unknown" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Implements getPrincipalPermissionSummary" 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"]
   getPrincipalPermissionSummary(principal: Principal): object {
     if (principal.type === 'human') {
       return {
@@ -1301,49 +1039,27 @@ class _PermissionEngineInternal {
     return { type: 'unknown' }
   }
 }
-// ─── CHUNK_END: PERMISSIONS_PERMISSION_SUMMARY ────────────────────────────────────────────────
-
-// ─── CHUNK_START: PERMISSIONS_SINGLETON_AND_EXPORTS ──────────────────────────────────────────────
-// ─── SINGLETON EXPORT ────────────────────────────────────────────────────────
-
-/**
- * The single shared PermissionEngine instance.
- *
- * This is the ONLY export that should be used for permission checks. Import this
- * directly or use the named legacy aliases below. Do not instantiate
- * `_PermissionEngineInternal` yourself.
- *
- * @stability stable
- * @audience both
- * @calledBy All 19 API handlers, tests, and custom code in v2-custom/
- *
- * @example API handler
- * ```ts
- * import { PermissionEngine } from './_shared/permissions'
- * const sanitized = await PermissionEngine.sanitizeRecordData(ctx, record, 'item')
- * ```
- *
- * @example Import usage (v2-custom/)
- * ```ts
- * import { PermissionEngine } from '../_shared/index'
- * const allowed = await PermissionEngine.canPrincipalAccessRecord(principal, record, 'read')
- * ```
- */
-export const PermissionEngine: _PermissionEngineInternal = _PermissionEngineInternal.getInstance()
 
-// ─── LEGACY EXPORTS ───────────────────────────────────────────────────────────
+// CIL[END chunk_id="permissions_getprincipalsummary_1784066609"]
+// CIL[BEGIN chunk_id="permissions_exports_1784066609" type="exports" identity="exports" parent="none"]
+// CIL[DOC-MACRO purpose="exports"]
+// CIL[DOC-RESPONSIBILITY responsibility="Handle exports"]
+// CIL[DOC-CONTEXT module="exports" layer="unknown" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Implements exports" 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"]
+export const PermissionEngine: _PermissionEngineInternal = _PermissionEngineInternal.getInstance()
 
-/**
- * Legacy named exports — bound methods on the singleton for backward compatibility.
- * Prefer importing `PermissionEngine` and calling methods on it directly.
- * These will be removed in a future version.
- *
- * @deprecated Use `PermissionEngine.<methodName>()` instead.
- * @stability internal
- */
 export const resolveFirstSurfacePermissions = PermissionEngine.resolveFirstSurfacePermissions.bind(PermissionEngine)
 export const isSystemAdmin = PermissionEngine.isSystemAdmin.bind(PermissionEngine)
 export const canAccessRecord = PermissionEngine.canAccessRecord.bind(PermissionEngine)
 export const sanitizeRecordData = PermissionEngine.sanitizeRecordData.bind(PermissionEngine)
 export const validateUpdatePermissions = PermissionEngine.validateUpdatePermissions.bind(PermissionEngine)
-// ─── CHUNK_END: PERMISSIONS_SINGLETON_AND_EXPORTS ────────────────────────────────────────────────
+// CIL[END chunk_id="permissions_exports_1784066609"]