spine-framework 0.1.0

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

@@ -0,0 +1,156 @@
+/**
+ * @module agent-runner
+ * @audience both
+ * @layer shared-core
+ * @stability stable
+ *
+ * AI agent inference orchestrator with RAG, tool dispatch, and confidence-based
+ * escalation. All agent behavior is defined via JSONB configuration stored in
+ * existing schema tables — no dedicated migrations are needed.
+ *
+ * Configuration resolution chain (highest to lowest priority):
+ *   1. `thread.data.agent_id` → `thread.type.design_schema.default_agent_id`
+ *   2. `thread.data.prompt_config_id` → `agent.metadata.default_prompt_config_id`
+ *
+ * Inference loop (per `runAgent` call):
+ *   1. `resolveAgentConfig` — resolve agent + prompt_config from thread
+ *   2. Save user message to `messages` table
+ *   3. `executeAgentInference` — iterative tool-call loop (max 5 iterations):
+ *      a. `buildContext` — assemble system prompt + RAG + history + tools
+ *      b. `callInference` — call OpenAI-compatible API (or return mock)
+ *      c. `dispatchTools` — execute any tool_calls via actions table
+ *      d. Rebuild context with tool results and repeat
+ *   4. Confidence check — if below threshold, `handleEscalation`
+ *   5. Save agent response to `messages` table
+ *   6. Emit `agent.inference.completed` audit log
+ *
+ * Environment variables used by `callInference`:
+ *   - `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` / `LLM_API_KEY` — LLM auth
+ *   - `OPENAI_BASE_URL` / `LLM_BASE_URL` — API base URL (default: OpenAI)
+ *   - `LLM_DEFAULT_MODEL` — model name fallback (default: 'gpt-4o')
+ *
+ * INVARIANT: if no API key is set, `callInference` returns a mock response
+ *   instead of throwing — safe for local development without credentials.
+ * INVARIANT: `runAgent` throws on critical failures (config missing, inference
+ *   error) — callers must handle the rejection.
+ * INVARIANT: `resolveAgentConfig` returns null (not throws) on missing config;
+ *   `runAgent` converts this to a throw.
+ *
+ * @seeAlso pipeline-runner.ts (tool dispatch calls runPipeline for run_pipeline tool)
+ * @seeAlso audit.ts (emitAudit for agent.inference.* events)
+ * @seeAlso index.ts (runAgent, resolveAgentConfig re-exported)
+ */
+import { CoreContext } from './middleware';
+/**
+ * Resolved agent configuration bundle. Output of `resolveAgentConfig`.
+ * Passed to `executeAgentInference` and `buildContext`.
+ *
+ * @outputSpec agent: ai_agents row (system_prompt, model_config, metadata)
+ * @outputSpec promptConfig: prompt_configs row (context_template,
+ *   knowledge_sources, available_tools, confidence_threshold, escalation_*)
+ * @outputSpec thread: threads row with joined type record
+ * @outputSpec threadType: types row (design_schema.default_agent_id)
+ */
+export interface AgentConfig {
+    agent: any;
+    promptConfig: any;
+    thread: any;
+    threadType: any;
+}
+/**
+ * Structured result from a single LLM inference call.
+ *
+ * @outputSpec content: string — agent response text
+ * @outputSpec confidence: number — 0-1 score; derived from logprobs or 0.85 default
+ * @outputSpec tool_calls: ToolCall[] | undefined — tools the model wants to call
+ * @outputSpec metadata: { model, usage, finish_reason } | undefined
+ */
+export interface InferenceResult {
+    content: string;
+    confidence: number;
+    tool_calls?: ToolCall[];
+    metadata?: Record<string, any>;
+}
+/**
+ * A single tool invocation requested by the LLM in an `InferenceResult`.
+ *
+ * @inputSpec tool: string — action.slug to look up in the actions table
+ * @inputSpec params: Record<string, any> — parsed from OpenAI function call arguments
+ * @inputSpec id: string — opaque tool_call ID from the LLM response
+ */
+export interface ToolCall {
+    tool: string;
+    params: Record<string, any>;
+    id: string;
+}
+/**
+ * Result of executing a single `ToolCall`.
+ *
+ * @outputSpec tool: string — mirrors ToolCall.tool
+ * @outputSpec result: any — handler return value on success; null on error
+ * @outputSpec error: string | undefined — error message if execution failed
+ * @outputSpec id: string — mirrors ToolCall.id for correlation
+ */
+export interface ToolResult {
+    tool: string;
+    result: any;
+    error?: string;
+    id: string;
+}
+/**
+ * Main entry point: run a full agent inference cycle for a user message.
+ *
+ * Saves the user message, runs the inference loop (with tool calls), checks
+ * confidence, saves the agent response, and emits audit logs.
+ *
+ * @param threadId - UUID of the thread to run inference on
+ * @param userMessage - Raw message text from the user
+ * @param ctx - CoreContext with accountId, principal, requestId
+ * @returns Promise<any> — the saved agent message record from the `messages` table
+ * @throws Error — if agent config cannot be resolved, or LLM inference fails
+ * @inputSpec threadId: string — valid UUID in threads table
+ * @inputSpec userMessage: string — non-empty message text
+ * @inputSpec ctx.accountId: string | null — used to scope DB lookups
+ * @outputSpec messages row — the inserted agent reply with content and metadata
+ * @sideEffects DB write: inserts 2 messages rows (user + agent)
+ * @sideEffects DB write: emitAudit (agent.inference.completed or agent.inference.failed)
+ * @sideEffects HTTP call: callInference (LLM API)
+ * @sideEffects DB write (conditional): handleEscalation if confidence < threshold
+ * @calledBy functions/ai-agents.ts handler for POST ?action=run
+ * @calledBy v2-custom/ import callers
+ * @calls resolveAgentConfig, saveMessage, executeAgentInference,
+ *   handleEscalation, emitAudit
+ * @testUnit tests/unit/agent-runner.test.ts
+ * @testIntegration tests/integration/agent-runner.test.ts
+ *
+ * @example API handler usage
+ * ```ts
+ * import { runAgent } from './_shared/index'
+ * const agentMsg = await runAgent(body.thread_id, body.message, ctx)
+ * return agentMsg
+ * ```
+ */
+export declare function runAgent(threadId: string, userMessage: string, ctx: CoreContext): Promise<any>;
+/**
+ * Resolves the agent, prompt config, thread, and thread type for a given thread.
+ *
+ * Resolution priority:
+ *   - `agent_id`: `thread.data.agent_id` → `thread.type.design_schema.default_agent_id`
+ *   - `prompt_config_id`: `thread.data.prompt_config_id` →
+ *     `agent.metadata.default_prompt_config_id`
+ *
+ * Returns `null` (does not throw) when any required record is missing. `runAgent`
+ * converts a null return to a thrown Error.
+ *
+ * @param threadId - UUID of the thread
+ * @param ctx - CoreContext (requestId used for error logging)
+ * @returns Promise<AgentConfig | null> — null if config cannot be resolved
+ * @throws never — errors logged to console, returns null
+ * @inputSpec threadId: string — valid UUID in threads table
+ * @outputSpec AgentConfig | null
+ * @sideEffects DB reads: threads (with type join), ai_agents, prompt_configs
+ * @calledBy runAgent
+ * @testUnit tests/unit/agent-runner.test.ts — 'resolveAgentConfig'
+ */
+export declare function resolveAgentConfig(threadId: string, ctx: CoreContext): Promise<AgentConfig | null>;
+//# sourceMappingURL=agent-runner.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"agent-runner.d.ts","sourceRoot":"","sources":["../../../.framework/functions/_shared/agent-runner.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAM1C;;;;;;;;;GASG;AACH,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,GAAG,CAAA;IACV,YAAY,EAAE,GAAG,CAAA;IACjB,MAAM,EAAE,GAAG,CAAA;IACX,UAAU,EAAE,GAAG,CAAA;CAChB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,CAAC,EAAE,QAAQ,EAAE,CAAA;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CAC/B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAC3B,EAAE,EAAE,MAAM,CAAA;CACX;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,GAAG,CAAA;IACX,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,EAAE,EAAE,MAAM,CAAA;CACX;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAsB,QAAQ,CAC5B,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,GAAG,CAAC,CA0Ed;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAmE7B"}

package/dist/functions/_shared/app-manifest.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @module app-manifest
+ * @audience core-contributor
+ * @layer shared-util
+ * @stability evolving
+ *
+ * Utility for loading and merging app manifests with database records.
+ * Enables file-first app configuration with database tracking installations.
+ *
+ * **Pattern:**
+ * 1. Manifest files in custom/apps/{slug}/manifest.json are source of truth
+ * 2. Database tracks which tenant has which app installed/enabled
+ * 3. This utility merges both sources for the API response
+ *
+ * @seeAlso apps.ts (uses this for manifest-driven responses)
+ * @seeAlso 015_simplify_apps_table.sql (database structure)
+ */
+export interface AppManifest {
+    name: string;
+    slug: string;
+    description?: string;
+    version?: string;
+    required_roles: string[];
+    routes: string[];
+    nav_items: NavItem[];
+    features?: string[];
+    dependencies?: string[];
+    entry_point: string;
+    is_public?: boolean;
+    auth_required?: boolean;
+}
+export interface NavItem {
+    title: string;
+    path: string;
+    icon?: string;
+    order?: number;
+    children?: NavItem[];
+}
+/**
+ * Loads a manifest.json file from the filesystem.
+ *
+ * @param manifestPath - Relative path to manifest (e.g., 'custom/apps/cortex/manifest.json')
+ * @returns Parsed manifest or null if not found
+ */
+export declare function loadManifest(manifestPath: string): AppManifest | null;
+/**
+ * Clears the manifest cache. Useful for testing.
+ */
+export declare function clearManifestCache(): void;
+/**
+ * Merges database app record with manifest data.
+ * Manifest takes precedence for metadata fields.
+ *
+ * @param dbRecord - App record from app_definitions table
+ * @returns Merged app data for API response
+ */
+export declare function mergeWithManifest(dbRecord: any): any;
+/**
+ * Lists all available manifests from filesystem.
+ * Used for initial discovery before database tracking.
+ *
+ * @returns Array of discovered app slugs and their paths
+ */
+export declare function discoverManifests(): Array<{
+    slug: string;
+    path: string;
+}>;
+//# sourceMappingURL=app-manifest.d.ts.map

package/dist/functions/_shared/app-manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-manifest.d.ts","sourceRoot":"","sources":["../../../.framework/functions/_shared/app-manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,cAAc,EAAE,MAAM,EAAE,CAAA;IACxB,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,SAAS,EAAE,OAAO,EAAE,CAAA;IACpB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;IACnB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;IACvB,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB;AAED,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAA;CACrB;AAKD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAiCrE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,GAAG,GAAG,GAAG,CA2DpD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,IAAI,KAAK,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,CAAC,CAcvE"}

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

@@ -0,0 +1,91 @@
+/**
+ * @module audit
+ * @audience both
+ * @layer shared-core
+ * @stability stable
+ *
+ * Unified audit logging for all operations in Spine. Every state-changing
+ * operation should call `emitAudit` to write a structured row to the `logs`
+ * table with full principal provenance. Audit failures never throw — a failed
+ * log write must never break the operation that triggered it.
+ *
+ * INVARIANT: always call `emitAudit` after a successful write, not before.
+ *   Pass `result: 'failure'` only when the operation itself failed.
+ * INVARIANT: never pass sensitive secrets (API keys, tokens) in metadata.
+ *
+ * @seeAlso principal.ts (formatPrincipalForAudit — shapes the principal field)
+ * @seeAlso middleware.ts (CoreContext — ctx.requestId ties logs to HTTP requests)
+ * @seeAlso logs.ts (API handler that queries the logs table)
+ * @seeAlso permissions.ts (getPrincipalPermissionSummary — used in metadata)
+ */
+import { CoreContext } from './middleware';
+/**
+ * @chunk-id    SHARED_AUDIT_EMIT_1_0_0
+ * @version     1.0.0
+ * @hash        d9c3dbc103f5f2f0543dc4c154bbad256e59c885643a20bc20ca07198eabd67c
+ * @macro       Audit Log Emitter
+ * @micro       Writes structured audit logs to logs table with principal provenance
+ * @inputs      ctx: CoreContext — Request context with principal and database
+ * @inputs      action: string — Dot-namespaced action (e.g. 'items.create')
+ * @inputs      target: {type, id?, account_id?} — Resource being acted upon
+ * @inputs      metadata: {changes?, result?, error?, ...} — Optional context
+ * @outputs     void — Always resolves, never rejects
+ * @depends-on  [adminDb, formatPrincipalForAudit]
+ * @depended-by [All state-changing API functions, pipeline-runner, trigger-engine]
+ * @side-effects [DB insert to logs table, console.error on failure]
+ * @tags        audit, logging, security, compliance
+ */
+export declare function emitAudit(ctx: CoreContext, action: string, target: {
+    type: string;
+    id?: string;
+    account_id?: string;
+}, metadata?: {
+    changes?: {
+        before?: any;
+        after?: any;
+    };
+    result?: 'success' | 'failure' | 'denied';
+    error?: string;
+    [key: string]: any;
+}): Promise<void>;
+/**
+ * @chunk-id    SHARED_AUDIT_EMIT_LOG_1_0_0
+ * @version     1.0.0
+ * @hash        148fb1ce7badf1d3df08e2daa38bac4c084c94ba2f262c782c9df092a22890dd
+ * @macro       Legacy Audit Log Wrapper
+ * @micro       Backward compatibility wrapper around emitAudit
+ * @inputs      ctx: CoreContext — Request context
+ * @inputs      eventType: string — Action string (maps to emitAudit's action)
+ * @inputs      target: {type, id} | undefined — Resource target
+ * @inputs      changes: {before?, after?} | undefined — Change data
+ * @inputs      metadata: Record<string, any> — Additional context
+ * @outputs     void — Always resolves
+ * @depends-on  [emitAudit]
+ * @depended-by [Legacy code, should not be used in new code]
+ * @side-effects [DB insert via emitAudit, console.error on failure]
+ * @tags        audit, logging, legacy, wrapper, deprecated
+ */
+export declare function emitLog(ctx: CoreContext, eventType: string, target?: {
+    type: string;
+    id: string;
+}, changes?: {
+    before?: any;
+    after?: any;
+}, metadata?: Record<string, any>): Promise<void>;
+/**
+ * @chunk-id    SHARED_AUDIT_EMIT_ACTIVITY_1_0_0
+ * @version     1.0.0
+ * @hash        58e532a743fdae480ca24d311be66e82612477309270ec7462fd7dfd695d5282
+ * @macro       Legacy Activity Logger
+ * @micro       Wraps emitLog with activity. prefix for backward compatibility
+ * @inputs      ctx: CoreContext — Request context
+ * @inputs      type: string — Activity type (prefixed with 'activity.')
+ * @inputs      details: Record<string, any> — Metadata context
+ * @outputs     void — Always resolves
+ * @depends-on  [emitLog]
+ * @depended-by [Legacy code, should not be used in new code]
+ * @side-effects [DB insert via emitLog → emitAudit, console.error on failure]
+ * @tags        audit, logging, legacy, activity, deprecated
+ */
+export declare function emitActivity(ctx: CoreContext, type: string, details?: Record<string, any>): Promise<void>;
+//# sourceMappingURL=audit.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../../.framework/functions/_shared/audit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAO1C;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,SAAS,CAC7B,GAAG,EAAE,WAAW,EAChB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,EAC1D,QAAQ,CAAC,EAAE;IACT,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,GAAG,CAAC;QAAC,KAAK,CAAC,EAAE,GAAG,CAAA;KAAE,CAAA;IACvC,MAAM,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAA;IACzC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;CACnB,GACA,OAAO,CAAC,IAAI,CAAC,CA0Bf;AAMD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,OAAO,CAC3B,GAAG,EAAE,WAAW,EAChB,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,EACrC,OAAO,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,GAAG,CAAC;IAAC,KAAK,CAAC,EAAE,GAAG,CAAA;CAAE,EACvC,QAAQ,GAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAM,GACjC,OAAO,CAAC,IAAI,CAAC,CAcf;AAID;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAM,GAChC,OAAO,CAAC,IAAI,CAAC,CAEf"}

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

@@ -0,0 +1,125 @@
+/**
+ * @module db
+ * @audience both
+ * @layer shared-core
+ * @stability stable
+ *
+ * Supabase client factory and PostgREST join helpers. This module owns the
+ * two-client pattern that is central to Spine's security model: `adminDb`
+ * bypasses RLS for system operations; `getUserDb` enforces RLS for all
+ * human-principal requests. Never use `adminDb` for user-scoped queries —
+ * doing so silently bypasses account isolation.
+ *
+ * @seeAlso principal.ts (getPrincipalDb selects between these two clients)
+ * @seeAlso middleware.ts (ctx.db is set from getPrincipalDb at request time)
+ */
+/**
+ * Service-role Supabase client. Bypasses Row Level Security.
+ *
+ * Use this ONLY for:
+ * - System/cron operations that must cross account boundaries (`system-cron.ts`)
+ * - Principal resolution lookups (`principal.ts` — resolving auth_uid to person)
+ * - Machine principal validation RPCs
+ * - Test helpers that need to seed/clean data across accounts
+ *
+ * Do NOT use this in request handlers for user-scoped data reads or writes.
+ * Always prefer `ctx.db` (set by `getPrincipalDb` in middleware) for those.
+ *
+ * @inputSpec SUPABASE_URL: string — valid Supabase project URL, required
+ * @inputSpec SUPABASE_SERVICE_ROLE_KEY: string — service role JWT, required
+ * @outputSpec SupabaseClient — PostgREST client scoped to `dbSchema`, RLS disabled
+ * @sideEffects none (client construction only)
+ * @calledBy principal.ts, middleware.ts, system-cron.ts, permissions.ts,
+ *   tests/integration/helpers.ts
+ * @calls createClient (supabase-js)
+ * @testUnit tests/unit/pipeline-runner.test.ts — mocked via vi.mock
+ * @testIntegration tests/integration/helpers.ts — used directly as adminDb
+ *
+ * @example API handler (system operation)
+ * ```ts
+ * import { adminDb } from './_shared/db'
+ * const { data } = await adminDb.from('types').select('*').eq('slug', 'item')
+ * ```
+ *
+ * @example Import usage (v2-custom/ — system-level only)
+ * ```ts
+ * import { adminDb } from '../_shared/index'
+ * // Only use adminDb if your custom code runs as a system/cron principal
+ * ```
+ */
+export declare const adminDb: import("@supabase/supabase-js").SupabaseClient<any, "public", string, any, any>;
+/**
+ * @chunk-id    SHARED_DB_GET_USER_DB_1_0_0
+ * @version     1.0.0
+ * @hash        af3c792634c60ced1c1c4184cfc6c20add90ab97eb62f7e46bdf40ae2899a0f8
+ * @macro       User Database Client Factory
+ * @micro       Creates RLS-enforced Supabase client for specific user JWT
+ * @inputs      jwt: string — Valid Supabase JWT from Authorization header
+ * @outputs     SupabaseClient — PostgREST client with RLS enforced
+ * @depends-on  [createClient, supabaseUrl, supabaseAnonKey, dbSchema]
+ * @depended-by [principal.ts, middleware.ts]
+ * @side-effects [Client construction with Authorization header]
+ * @tags        database, supabase, rls, authentication, user-scoped
+ */
+export declare function getUserDb(jwt: string): import("@supabase/supabase-js").SupabaseClient<any, "public", string, any, any>;
+/**
+ * Standard shape returned by all Supabase PostgREST queries.
+ *
+ * Both `data` and `error` follow the Supabase JS client convention: on success,
+ * `error` is null; on failure, `data` is null and `error` contains the Postgres
+ * error details. Always check `error` before using `data`.
+ *
+ * @inputSpec T — the expected shape of a successful result row
+ * @outputSpec data: T | null — the query result, null on error
+ * @outputSpec error: any — null on success, Postgres/PostgREST error object on failure
+ * @calledBy used as return type annotation across all functions/*.ts handlers
+ *
+ * @example
+ * ```ts
+ * const result: DbResult<Item> = await adminDb.from('items').select('*').single()
+ * if (result.error) throw result.error
+ * return result.data!
+ * ```
+ */
+export type DbResult<T> = {
+    data: T | null;
+    error: any;
+};
+/**
+ * PostgREST relationship hint strings for all foreign keys in the public schema.
+ *
+ * These strings are interpolated into `.select()` calls to eager-load related
+ * records in a single query. They use explicit `!fk_column` hints to resolve
+ * ambiguous relationships — required when a table has multiple FKs to the same
+ * target table, or when the FK column name doesn't follow PostgREST's default
+ * `tablename_id` inference convention (e.g. `created_by` → `people.id`).
+ *
+ * Only add a join here when it is used in two or more handlers. One-off joins
+ * should be written inline.
+ *
+ * @inputSpec none — these are static string constants
+ * @outputSpec string — valid PostgREST embed expression for use in .select()
+ * @sideEffects none
+ * @calledBy types.ts, apps.ts, pipelines.ts, triggers.ts, admin-data.ts, and others
+ * @testUnit none — these are string constants; incorrect joins fail at runtime
+ * @testIntegration tests/integration/admin-data-accounts.test.ts — exercises joins.type
+ *
+ * @example
+ * ```ts
+ * import { joins } from './_shared/db'
+ * const { data } = await ctx.db
+ *   .from('items')
+ *   .select(`*, ${joins.type}, ${joins.app}`)
+ * // Returns items with nested type and app objects
+ * ```
+ */
+export declare const joins: {
+    type: string;
+    app: string;
+    ownerAccount: string;
+    createdBy: string;
+    parentAccount: string;
+    role: string;
+    pipeline: string;
+};
+//# sourceMappingURL=db.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../../../.framework/functions/_shared/db.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AA2BH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,OAAO,iFAIlB,CAAA;AAGF;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,mFAWpC;AAKD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI;IACxB,IAAI,EAAE,CAAC,GAAG,IAAI,CAAA;IACd,KAAK,EAAE,GAAG,CAAA;CACX,CAAA;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,KAAK;;;;;;;;CAQjB,CAAA"}