spine-framework 0.1.0

package/dist/functions/_shared/pipeline-runner.d.ts

@@ -0,0 +1,124 @@
+/**
+ * @module pipeline-runner
+ * @audience both
+ * @layer shared-core
+ * @stability stable
+ *
+ * Sequential pipeline execution engine. A pipeline is a named list of stages
+ * (`PipelineStage[]`) stored in `pipelines.stages`. Each stage references an
+ * `action` record by `stage_type` slug. Stages run sequentially; a failed stage
+ * halts execution unless `stage.continue_on_error` is set.
+ *
+ * Every execution creates a `pipeline_executions` row (status: running →
+ * completed | failed) and emits an audit log on completion or failure.
+ *
+ * Built-in stage handlers (no external config required):
+ *   - `update_item`      — update a record by ID
+ *   - `create_record`    — insert a new record
+ *   - `http_request`     — fetch any HTTP endpoint
+ *   - `send_notification`— insert watchers notification rows
+ *   - `run_pipeline`     — trigger a nested pipeline (self-recursion blocked)
+ *   - `search_knowledge` — full-text + fallback search on embeddings table
+ *   - `query_items`      — filtered query on any table
+ *   - `agent_inference`  — call an external LLM webhook or return a mock
+ *
+ * INVARIANT: `adminDb` (service role) is used for all DB writes — stage
+ *   execution runs as the pipeline's machine principal, not the end user.
+ * INVARIANT: `run_pipeline` handler blocks self-referential execution
+ *   (`config._pipelineId === pipeline_id`) to prevent infinite loops.
+ * INVARIANT: `runPipeline` never throws — failures are captured in the
+ *   returned `ExecutionResult` with `status: 'failed'`.
+ *
+ * @seeAlso trigger-engine.ts (calls runPipeline when a trigger fires)
+ * @seeAlso agent-runner.ts (calls runPipeline for agentic tool calls)
+ * @seeAlso audit.ts (emitAudit called on pipeline.completed / pipeline.failed)
+ * @seeAlso index.ts (runPipeline re-exported for v2-custom/ and CLI)
+ */
+import { CoreContext } from './middleware';
+/**
+ * Result of a single pipeline stage execution.
+ *
+ * @outputSpec stageIndex: number — 0-based position in the pipeline's stages array
+ * @outputSpec stageType: string — action slug (e.g. 'update_item', 'http_request')
+ * @outputSpec status: 'success' | 'failed' | 'skipped'
+ * @outputSpec output: any | undefined — handler return value on success
+ * @outputSpec error: string | undefined — error message on failure
+ * @outputSpec durationMs: number — wall-clock time for this stage
+ */
+export interface StageResult {
+    stageIndex: number;
+    stageType: string;
+    status: 'success' | 'failed' | 'skipped';
+    output?: any;
+    error?: string;
+    durationMs: number;
+}
+/**
+ * Top-level result of a `runPipeline` call. Stored in `pipeline_executions.result`.
+ *
+ * @outputSpec executionId: string — UUID of the pipeline_executions row
+ * @outputSpec pipelineId: string — UUID of the pipeline that was run
+ * @outputSpec status: 'completed' | 'failed' | 'cancelled'
+ * @outputSpec stages: StageResult[] — per-stage results in execution order
+ * @outputSpec durationMs: number — total wall-clock time
+ * @outputSpec error: string | undefined — top-level error message on failure
+ */
+export interface ExecutionResult {
+    executionId: string;
+    pipelineId: string;
+    status: 'completed' | 'failed' | 'cancelled';
+    stages: StageResult[];
+    durationMs: number;
+    error?: string;
+}
+/**
+ * Executes a pipeline by ID, running its stages sequentially.
+ *
+ * Execution lifecycle:
+ *   1. Load pipeline record (`pipelines` table, `is_active = true`)
+ *   2. Insert `pipeline_executions` row with `status: 'running'`
+ *   3. For each stage: load action → merge config → call `executeStage`
+ *   4. On stage failure: push failed StageResult; stop unless `continue_on_error`
+ *   5. Update `pipeline_executions` to `completed` or `failed`
+ *   6. Emit `pipeline.completed` or `pipeline.failed` audit log
+ *   7. Return `ExecutionResult` (never throws; failures are in result.status)
+ *
+ * @param pipelineId - UUID of the pipeline to run (must be active)
+ * @param triggerData - Arbitrary context passed to each stage as `_triggerData`
+ * @param ctx - CoreContext with principal and accountId for audit and stage writes
+ * @returns Promise<ExecutionResult> — always resolves; never throws
+ * @throws Error('Pipeline not found or inactive') — only if pipeline lookup fails
+ *   before execution begins (throws before creating the execution row)
+ * @throws Error('Failed to create execution') — if execution row insert fails
+ * @inputSpec pipelineId: string — valid UUID of a pipeline in pipelines table
+ * @inputSpec triggerData: any — JSON-serializable; stored in trigger_data column
+ * @inputSpec ctx.accountId: string | null — stamped on execution row
+ * @inputSpec ctx.principal.id: string — stamped as created_by on execution row
+ * @outputSpec ExecutionResult with status, stages, durationMs
+ * @sideEffects DB write: inserts pipeline_executions row; updates it on completion
+ * @sideEffects DB write: emitAudit to logs table
+ * @calledBy trigger-engine.ts (on trigger fire)
+ * @calledBy agent-runner.ts (tool call dispatch)
+ * @calledBy stageHandlers.run_pipeline (nested execution)
+ * @calledBy v2-custom/ import callers and CLI
+ * @calls executeStage, adminDb, emitAudit
+ * @testUnit tests/unit/pipeline-runner.test.ts
+ * @testIntegration tests/integration/pipeline-runner.test.ts
+ *
+ * @example API handler trigger
+ * ```ts
+ * import { runPipeline } from './_shared/index'
+ * const result = await runPipeline(body.pipeline_id, body.data, ctx)
+ * if (result.status === 'failed') return error(result.error!, 500)
+ * return result
+ * ```
+ *
+ * @example Import usage (v2-custom/)
+ * ```ts
+ * import { runPipeline, SYSTEM_PRINCIPAL, adminDb, CoreContext } from '../_shared/index'
+ * const ctx: CoreContext = { principal: SYSTEM_PRINCIPAL, accountId: MY_ACCOUNT, db: adminDb, requestId: crypto.randomUUID() }
+ * const result = await runPipeline('pipeline-uuid', { source: 'import' }, ctx)
+ * ```
+ */
+export declare function runPipeline(pipelineId: string, triggerData: any, ctx: CoreContext): Promise<ExecutionResult>;
+//# sourceMappingURL=pipeline-runner.d.ts.map

package/dist/functions/_shared/pipeline-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline-runner.d.ts","sourceRoot":"","sources":["../../../.framework/functions/_shared/pipeline-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAS1C;;;;;;;;;GASG;AACH,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAA;IACxC,MAAM,CAAC,EAAE,GAAG,CAAA;IACZ,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,MAAM,CAAA;IACnB,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAA;IAC5C,MAAM,EAAE,WAAW,EAAE,CAAA;IACrB,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAiBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,wBAAsB,WAAW,CAC/B,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,GAAG,EAChB,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,eAAe,CAAC,CAgK1B"}

package/dist/functions/_shared/principal.d.ts

@@ -0,0 +1,284 @@
+/**
+ * @module principal
+ * @audience both
+ * @layer shared-core
+ * @stability stable
+ *
+ * Unified identity abstraction for all actors in Spine v2. Every request —
+ * whether from a human via JWT, an integration via API key, a scheduled cron
+ * job, or an internal trigger — resolves to a single `Principal` object before
+ * any permission check or DB query occurs.
+ *
+ * Resolution order in `resolvePrincipal`:
+ *   1. `x-api-key` header  → machine principal (external integration)
+ *   2. `x-cron-id` header  → machine principal (scheduled job)
+ *   3. `x-trigger-id` header → machine principal (event trigger)
+ *   4. `Authorization: Bearer <jwt>` → human principal
+ *   5. (none)              → ANONYMOUS_PRINCIPAL (rejected by createHandler)
+ *
+ * INVARIANT: `resolvePrincipal` always returns a Principal, never null.
+ *   ANONYMOUS_PRINCIPAL is the sentinel for unauthenticated requests and is
+ *   rejected by `createHandler` before the handler runs.
+ * INVARIANT: `adminDb` is used for all principal resolution lookups to avoid
+ *   circular dependencies with RLS (which itself depends on the resolved principal).
+ * INVARIANT: never store `authContext.jwt` or `authContext.apiKey` in logs.
+ *   Use `formatPrincipalForAudit` which strips these fields.
+ *
+ * @seeAlso db.ts (adminDb, getUserDb — used for resolution and client selection)
+ * @seeAlso middleware.ts (createHandler calls resolvePrincipal, getPrincipalDb)
+ * @seeAlso permissions.ts (PermissionEngine.isSystemAdmin, canPrincipalAccessRecord)
+ * @seeAlso audit.ts (formatPrincipalForAudit — safe audit serialization)
+ */
+/**
+ * Unified identity abstraction for all actors in Spine.
+ *
+ * Every request resolves to a `Principal` before any permission or DB access.
+ * The `type` field gates which optional fields are populated:
+ *   - `'human'` → `roles`, `displayName`, `email`, `authContext.jwt`
+ *   - `'machine'` → `scopes`, `machineType`, `isInternal`, `authContext.apiKey`
+ *
+ * The `provenance` object is always populated and is the primary audit trail
+ * field. It must not be modified after resolution.
+ *
+ * @inputSpec none — this is a pure type definition
+ * @calledBy middleware.ts (RequestContext.principal), permissions.ts (all methods),
+ *   audit.ts (formatPrincipalForAudit), tests/integration/helpers.ts (makeTestCtx)
+ */
+export interface Principal {
+    /** Unique identifier — person UUID (human) or machine principal UUID (machine) */
+    id: string;
+    /** Actor type — gates which optional fields are populated */
+    type: 'human' | 'machine';
+    /** Primary account context; null for internal system principals */
+    accountId: string | null;
+    /** Role slugs from people.role_id → roles.slug; used by PermissionEngine */
+    roles?: string[];
+    /** Display name from people.display_name or people.email */
+    displayName?: string;
+    /** Email address from people.email or Supabase auth user */
+    email?: string;
+    /** Explicit permission grants (e.g., ['items:read', 'people:write', '*:*']) */
+    scopes?: string[];
+    /** Machine classification — determines UI visibility and default scopes */
+    machineType?: 'integration' | 'service_account' | 'internal' | 'timer';
+    /** Internal machines (cron, trigger, pipeline) are hidden from the UI */
+    isInternal?: boolean;
+    provenance: {
+        /** How this principal was authenticated */
+        sourceType: 'jwt' | 'api_key' | 'cron' | 'trigger' | 'manual' | 'webhook' | 'timer';
+        /** Person who authorized this principal (may be self for humans) */
+        createdBy: string | null;
+        /** Chain ID for trigger/pipeline sequences */
+        parentExecutionId?: string;
+        /** When this principal context was created */
+        invokedAt: string;
+        /** API key ID (for api_key source) */
+        apiKeyId?: string;
+        /** Schedule ID (for cron source) */
+        cronId?: string;
+        /** Trigger ID (for trigger source) */
+        triggerId?: string;
+        /** Timer ID (for timer source) */
+        timerId?: string;
+        /** Event ID that triggered this execution */
+        eventId?: string;
+        /** IP address of the requester */
+        ipAddress?: string;
+        /** User agent string */
+        userAgent?: string;
+    };
+    authContext?: {
+        /** JWT token for human-scoped DB client */
+        jwt?: string;
+        /** API key value for machine verification */
+        apiKey?: string;
+    };
+}
+/**
+ * Sentinel principal for unauthenticated requests.
+ *
+ * Returned by `resolvePrincipal` when no auth header is present. `createHandler`
+ * checks for `principal.id === 'anonymous'` and rejects the request with 401.
+ * Never use this principal for any DB access — it has no scopes or accountId.
+ *
+ * @stability stable
+ * @calledBy resolvePrincipal (returned when no auth header is present)
+ * @calledBy middleware.ts, requireUserContext, requireSystemContextWithAudit (checked against)
+ * @calledBy permissions.ts (all surface methods check for 'anonymous' and deny)
+ */
+export declare const ANONYMOUS_PRINCIPAL: Principal;
+/**
+ * System principal for internal Spine operations (cron, pipeline runner, trigger engine).
+ *
+ * Has `'*:*'` scope (all resources, all actions) and `isInternal: true`. When
+ * a `CoreContext` is constructed for a system operation (e.g. in v2-custom/ or
+ * the CLI), use `SYSTEM_PRINCIPAL` as the principal and `adminDb` as the db.
+ *
+ * Never expose this principal in an HTTP response or log the `authContext` field.
+ *
+ * @stability stable
+ * @calledBy tests/integration/helpers.ts (makeTestCtx)
+ * @calledBy CLI context construction
+ * @calledBy v2-custom/ system-level import callers
+ *
+ * @example Import usage (v2-custom/)
+ * ```ts
+ * import { CoreContext, SYSTEM_PRINCIPAL, adminDb } from '../_shared/index'
+ * const ctx: CoreContext = {
+ *   principal: SYSTEM_PRINCIPAL,
+ *   accountId: MY_ACCOUNT_ID,
+ *   db: adminDb,
+ *   requestId: crypto.randomUUID()
+ * }
+ * ```
+ */
+export declare const SYSTEM_PRINCIPAL: Principal;
+/**
+ * Main entry point for principal resolution. Called by `createHandler` on every
+ * HTTP request before the handler runs.
+ *
+ * Examines request headers in priority order and delegates to the appropriate
+ * resolver. Always returns a `Principal` — never throws for missing auth
+ * (returns `ANONYMOUS_PRINCIPAL` instead). Throws only on invalid/expired
+ * credentials (invalid API key, expired JWT, etc.).
+ *
+ * Resolution order:
+ *   1. `x-api-key` / `X-Api-Key` header → `resolveMachinePrincipal`
+ *   2. `x-cron-id` / `X-Cron-Id` header → `resolveCronPrincipal`
+ *   3. `x-trigger-id` / `X-Trigger-Id` header → `resolveTriggerPrincipal`
+ *   4. `Authorization: Bearer <jwt>` → `resolveHumanPrincipal`
+ *   5. (none matched) → `ANONYMOUS_PRINCIPAL`
+ *
+ * @param event - Raw Netlify event object with `headers` and optional `body`
+ * @returns Promise<Principal> — always resolves; throws on invalid credentials
+ * @throws Error — on invalid API key, invalid JWT, or missing DB records
+ * @inputSpec event.headers: Record<string, string> — HTTP request headers
+ * @outputSpec Principal — fully resolved principal with provenance populated
+ * @sideEffects DB reads: api_keys, schedules, triggers, people tables via sub-resolvers
+ * @calledBy middleware.ts (createHandler) — once per HTTP request
+ * @calls resolveMachinePrincipal | resolveCronPrincipal | resolveTriggerPrincipal |
+ *   resolveHumanPrincipal
+ * @testUnit tests/unit/principal.test.ts — 'resolvePrincipal' describe block
+ * @testIntegration tests/integration/auth.test.ts
+ */
+export declare function resolvePrincipal(event: any): Promise<Principal>;
+/**
+ * Checks whether a machine principal has been granted a specific scope.
+ *
+ * Scope matching supports three patterns:
+ *   1. Exact: `'items:read'` matches only `'items:read'`
+ *   2. Wildcard action: `'items:*'` matches `'items:read'`, `'items:write'`, etc.
+ *   3. Global wildcard: `'*:*'` matches any scope
+ *
+ * Returns `false` for non-machine principals — role-based checks use `humanHasRole`.
+ *
+ * @param principal - The principal to check
+ * @param scope - The required scope string in `'resource:action'` format
+ * @returns boolean — true if any of the principal's scopes grant the required scope
+ * @throws never
+ * @inputSpec principal.type: 'machine' — returns false for human principals
+ * @inputSpec scope: string — must be in 'resource:action' format
+ * @inputSpec principal.scopes: string[] — list of granted scope strings
+ * @outputSpec boolean
+ * @sideEffects none
+ * @calledBy permissions.ts (checkMachineScope), any custom code doing scope checks
+ * @testUnit tests/unit/principal.test.ts — 'machineHasScope' describe block
+ *
+ * @example
+ * ```ts
+ * import { machineHasScope } from '../_shared/index'
+ * if (!machineHasScope(principal, 'items:write')) {
+ *   return { error: 'Insufficient scope' }
+ * }
+ * ```
+ */
+export declare function machineHasScope(principal: Principal, scope: string): boolean;
+/**
+ * Checks whether a human principal has been assigned a specific role.
+ *
+ * Returns `false` for non-human (machine) principals — scope checks use
+ * `machineHasScope`. Role slugs come from `people.role_id → roles.slug`
+ * and are loaded at resolution time in `resolveHumanPrincipal`.
+ *
+ * @param principal - The principal to check
+ * @param roleSlug - The role slug to look for (e.g. 'system_admin', 'agent')
+ * @returns boolean — true if principal.roles includes the given slug
+ * @throws never
+ * @inputSpec principal.type: 'human' — returns false for machine principals
+ * @inputSpec roleSlug: string — must match exactly (case-sensitive)
+ * @inputSpec principal.roles: string[] | undefined
+ * @outputSpec boolean
+ * @sideEffects none
+ * @calledBy isSystemAdmin, permissions.ts (PermissionEngine.isSystemAdmin)
+ * @testUnit tests/unit/principal.test.ts — 'humanHasRole' describe block
+ */
+export declare function humanHasRole(principal: Principal, roleSlug: string): boolean;
+/**
+ * Returns true if the principal holds the `system_admin` role.
+ *
+ * This is the canonical system admin check used by `middleware.ts`
+ * (`requireSystemContextWithAudit`) and re-exported from `permissions.ts`
+ * (`PermissionEngine.isSystemAdmin`). system_admin bypasses all three
+ * permission surfaces.
+ *
+ * @param principal - The principal to check
+ * @returns boolean — true only if type='human' and roles includes 'system_admin'
+ * @throws never
+ * @inputSpec principal: Principal — any resolved principal
+ * @outputSpec boolean — false for machine principals, anonymous, or missing roles
+ * @sideEffects none
+ * @calledBy middleware.ts (requireSystemContextWithAudit), permissions.ts (PermissionEngine),
+ *   any handler doing system-admin-only checks
+ * @calls humanHasRole
+ * @testUnit tests/unit/principal.test.ts — 'isSystemAdmin' describe block
+ */
+export declare function isSystemAdmin(principal: Principal): boolean;
+/**
+ * Selects the correct Supabase database client for the given principal.
+ *
+ * This is the only place in the codebase where the two-client selection
+ * decision is made. The result is stored in `ctx.db` and used for all
+ * subsequent DB queries in the request.
+ *
+ * Selection logic:
+ *   - Human principal with JWT → `getUserDb(jwt)` — enforces RLS
+ *   - Machine principal → `adminDb` — RLS policies check machine ID in policies
+ *   - Anonymous → `adminDb` (but anonymous requests are rejected before DB access)
+ *
+ * @param principal - The resolved principal
+ * @returns SupabaseClient — RLS-scoped for humans, admin for machines
+ * @throws never
+ * @inputSpec principal.type: 'human' | 'machine'
+ * @inputSpec principal.authContext.jwt: string | undefined — required for human client
+ * @outputSpec SupabaseClient — getUserDb result (human) or adminDb (machine)
+ * @sideEffects none (client construction only)
+ * @calledBy middleware.ts (createHandler — `const ctxDb = getPrincipalDb(principal)`)
+ * @calls getUserDb (db.ts), adminDb (db.ts)
+ * @testUnit tests/unit/principal.test.ts — 'getPrincipalDb' describe block
+ */
+export declare function getPrincipalDb(principal: Principal): import("@supabase/supabase-js").SupabaseClient<any, "public", string, any, any>;
+/**
+ * Serializes a principal into a safe, structured object for audit log entries.
+ *
+ * Strips `authContext` entirely (never log JWT or API key values). The returned
+ * object is safe to store in the `metadata` JSONB column of the `logs` table.
+ *
+ * @param principal - Any resolved principal including ANONYMOUS_PRINCIPAL
+ * @returns object — audit-safe principal summary
+ * @throws never
+ * @inputSpec principal: Principal — any resolved principal
+ * @outputSpec { id, type, account_id } + role/scope fields depending on type
+ * @outputSpec authContext is NEVER included in output
+ * @sideEffects none
+ * @calledBy audit.ts (emitAudit — in metadata.principal)
+ * @testUnit tests/unit/principal.test.ts — 'formatPrincipalForAudit' describe block
+ *
+ * @example
+ * ```ts
+ * await emitAudit(ctx, 'items.delete', { type: 'item', id }, {
+ *   principal_snapshot: formatPrincipalForAudit(ctx.principal)
+ * })
+ * ```
+ */
+export declare function formatPrincipalForAudit(principal: Principal): object;
+//# sourceMappingURL=principal.d.ts.map

package/dist/functions/_shared/principal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"principal.d.ts","sourceRoot":"","sources":["../../../.framework/functions/_shared/principal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAwBH;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,SAAS;IACxB,kFAAkF;IAClF,EAAE,EAAE,MAAM,CAAA;IAEV,6DAA6D;IAC7D,IAAI,EAAE,OAAO,GAAG,SAAS,CAAA;IAEzB,mEAAmE;IACnE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IAGxB,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;IAEhB,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAA;IAEpB,4DAA4D;IAC5D,KAAK,CAAC,EAAE,MAAM,CAAA;IAGd,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IAEjB,2EAA2E;IAC3E,WAAW,CAAC,EAAE,aAAa,GAAG,iBAAiB,GAAG,UAAU,GAAG,OAAO,CAAA;IAEtE,yEAAyE;IACzE,UAAU,CAAC,EAAE,OAAO,CAAA;IAGpB,UAAU,EAAE;QACV,2CAA2C;QAC3C,UAAU,EAAE,KAAK,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAA;QAEnF,oEAAoE;QACpE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;QAExB,8CAA8C;QAC9C,iBAAiB,CAAC,EAAE,MAAM,CAAA;QAE1B,8CAA8C;QAC9C,SAAS,EAAE,MAAM,CAAA;QAGjB,sCAAsC;QACtC,QAAQ,CAAC,EAAE,MAAM,CAAA;QAEjB,oCAAoC;QACpC,MAAM,CAAC,EAAE,MAAM,CAAA;QAEf,sCAAsC;QACtC,SAAS,CAAC,EAAE,MAAM,CAAA;QAElB,kCAAkC;QAClC,OAAO,CAAC,EAAE,MAAM,CAAA;QAEhB,6CAA6C;QAC7C,OAAO,CAAC,EAAE,MAAM,CAAA;QAEhB,kCAAkC;QAClC,SAAS,CAAC,EAAE,MAAM,CAAA;QAElB,wBAAwB;QACxB,SAAS,CAAC,EAAE,MAAM,CAAA;KACnB,CAAA;IAKD,WAAW,CAAC,EAAE;QACZ,2CAA2C;QAC3C,GAAG,CAAC,EAAE,MAAM,CAAA;QAEZ,6CAA6C;QAC7C,MAAM,CAAC,EAAE,MAAM,CAAA;KAChB,CAAA;CACF;AAID;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAUjC,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAY9B,CAAA;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,GAAG,GAAG,OAAO,CAAC,SAAS,CAAC,CA2BrE;AAmUD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAgB5E;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAG5E;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAE3D;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,SAAS,mFAOlD;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,SAAS,GAAG,MAAM,CAgBpE"}

package/dist/functions/_shared/schema-utils.d.ts

@@ -0,0 +1,181 @@
+/**
+ * @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)
+ */
+/**
+ * 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)
+ */
+export interface ValidationSchema {
+    fields: Record<string, {
+        data_type: string;
+        required?: boolean;
+        [key: string]: any;
+    }>;
+}
+/**
+ * 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')
+ * ```
+ */
+export declare function generateValidationSchema(designSchema: any): 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')
+ * ```
+ */
+export declare function sanitizeFieldData(data: any, data_type: string, validation?: any): any;
+/**
+ * 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'
+ * ```
+ */
+export declare function formatFieldData(data: any, data_type: string, context?: any): any;
+/**
+ * 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)
+ * ```
+ */
+export declare function transformRecordData(data: Record<string, any>, validationSchema: ValidationSchema, operation: 'sanitize' | 'format', context?: any): Record<string, any>;
+//# sourceMappingURL=schema-utils.d.ts.map

package/dist/functions/_shared/schema-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-utils.d.ts","sourceRoot":"","sources":["../../../.framework/functions/_shared/schema-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAMH;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE;QACrB,SAAS,EAAE,MAAM,CAAA;QACjB,QAAQ,CAAC,EAAE,OAAO,CAAA;QAClB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;KACnB,CAAC,CAAA;CACH;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,wBAAwB,CAAC,YAAY,EAAE,GAAG,GAAG,gBAAgB,CAsC5E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,GAAG,EACT,SAAS,EAAE,MAAM,EACjB,UAAU,CAAC,EAAE,GAAG,GACf,GAAG,CAqDL;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,GAAG,EACT,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,GAAG,GACZ,GAAG,CA6BL;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACzB,gBAAgB,EAAE,gBAAgB,EAClC,SAAS,EAAE,UAAU,GAAG,QAAQ,EAChC,OAAO,CAAC,EAAE,GAAG,GACZ,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CA4BrB"}