@elevasis/sdk 1.24.0 → 1.25.0

package/dist/node/index.d.ts

@@ -1388,668 +1388,108 @@ declare const OntologyScopeSchema: z.ZodDefault<z.ZodObject<{
 }, z.core.$strip>>;
 type OntologyScope = z.infer<typeof OntologyScopeSchema>;
 
-/**
- * MetricsCollector
- * Tracks execution timing and ROI metrics
- */
-declare class MetricsCollector {
-    private timings;
-    private durationMs?;
-    /**
-     * Start a timer with a label
-     */
-    startTimer(label: string): void;
-    /**
-     * End a timer and calculate duration
-     * If label is 'execution', stores duration for metrics summary
-     */
-    endTimer(label: string): number | null;
-    /**
-     * Build execution metrics summary with optional ROI calculation
-     */
-    buildExecutionMetrics(metricsConfig?: ResourceMetricsConfig): ExecutionMetricsSummary;
+type JsonPrimitive = string | number | boolean | null;
+type JsonValue = JsonPrimitive | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/** Explicit interface needed to annotate the recursive SystemEntrySchema. */
+interface SystemEntry {
+    id: string;
+    label?: string;
+    title?: string;
+    description?: string;
+    kind?: 'product' | 'operational' | 'platform' | 'diagnostic';
+    parentSystemId?: string;
+    ui?: {
+        path: string;
+        surfaces: string[];
+        icon?: string;
+        order?: number;
+    };
+    lifecycle?: 'draft' | 'beta' | 'active' | 'deprecated' | 'archived';
+    responsibleRoleId?: string;
+    governedByKnowledge?: string[];
+    actions?: {
+        actionId: string;
+        intent: 'exposes' | 'consumes';
+        invocation?: unknown;
+    }[];
+    policies?: string[];
+    drivesGoals?: string[];
+    /** @deprecated Use lifecycle. Accepted for one publish cycle. */
+    status?: 'active' | 'deprecated' | 'archived';
+    path?: string;
+    icon?: string;
+    color?: string;
+    uiPosition?: 'sidebar-primary' | 'sidebar-bottom';
+    enabled?: boolean;
+    devOnly?: boolean;
+    requiresAdmin?: boolean;
+    order: number;
+    config?: Record<string, JsonValue>;
+    ontology?: OntologyScope;
+    systems?: Record<string, SystemEntry>;
+    subsystems?: Record<string, SystemEntry>;
 }
 
-interface BaseAICall {
-    callSequence: number;
-    callType: 'agent-reasoning' | 'agent-completion' | 'workflow-step' | 'tool' | 'other';
-    model: LLMModel;
-    inputTokens: number;
-    outputTokens: number;
-    costUsd: number;
-    latencyMs: number;
-    context?: AICallContext;
-}
-type AICallContext = AgentReasoningContext | AgentCompletionContext | WorkflowStepContext | ToolCallContext | OtherCallContext;
-interface AgentReasoningContext {
-    type: 'agent-reasoning';
-    iteration: number;
-    actionsPlanned?: string[];
-    sessionId?: string;
-    turnNumber?: number;
-}
-interface AgentCompletionContext {
-    type: 'agent-completion';
-    attempt: 1 | 2;
-    validationFailed?: boolean;
-    sessionId?: string;
-    turnNumber?: number;
-}
-interface WorkflowStepContext {
-    type: 'workflow-step';
-    stepId: string;
-    stepName?: string;
-    stepSequence?: number;
-}
-interface ToolCallContext {
-    type: 'tool';
-    toolName: string;
-    parentIteration?: number;
-    parentStepId?: string;
-}
-interface OtherCallContext {
-    type: 'other';
+declare const SurfaceTypeSchema: z.ZodEnum<{
+    dashboard: "dashboard";
+    settings: "settings";
+    graph: "graph";
+    list: "list";
+    page: "page";
+    detail: "detail";
+}>;
+interface SidebarSurfaceNode {
+    type: 'surface';
+    label: string;
+    path: string;
+    surfaceType: z.infer<typeof SurfaceTypeSchema>;
     description?: string;
-    metadata?: Record<string, unknown>;
-}
-type AICallRecord = BaseAICall;
-/**
- * Raw LLM usage data returned by adapters
- * Used as input to AIUsageCollector.record()
- */
-interface LLMUsageData {
-    model: LLMModel;
-    inputTokens: number;
-    outputTokens: number;
-    latencyMs: number;
-    /** Actual cost from provider in USD (when available, e.g., OpenRouter) */
-    cost?: number;
-}
-interface AIUsageSummary {
-    model: LLMModel;
-    totalInputTokens: number;
-    totalOutputTokens: number;
-    totalTokens: number;
-    totalCostUsd: number;
-    callCount: number;
-    calls: AICallRecord[];
-}
-interface ExecutionMetricsSummary {
-    durationMs?: number;
-    automationSavingsUsd?: number;
-}
-interface ResourceMetricsConfig {
-    estimatedManualMinutes: number;
-    hourlyLaborRateUsd: number;
-    confidenceLevel?: 'low' | 'medium' | 'high';
-    notes?: string;
+    icon?: string;
+    order?: number;
+    targets?: {
+        systems?: string[];
+        entities?: string[];
+        resources?: string[];
+        actions?: string[];
+    };
+    devOnly?: boolean;
+    requiresAdmin?: boolean;
 }
-
-/**
- * AIUsageCollector
- * Centralized token tracking that aggregates usage across all LLM calls in an execution
- */
-declare class AIUsageCollector {
-    private model;
-    private calls;
-    private callSequence;
-    /**
-     * Record a single AI call with usage metrics
-     *
-     * @param usage - Token usage and latency data from LLM adapter
-     * @param callType - Type discriminator (agent-reasoning, tool, etc.)
-     * @param context - Optional typed context specific to callType
-     */
-    record(usage: LLMUsageData, callType?: BaseAICall['callType'], context?: AICallContext): void;
-    /**
-     * Get aggregated summary of all AI calls
-     */
-    getSummary(): AIUsageSummary;
-    /**
-     * Check if any usage has been recorded
-     */
-    hasUsage(): boolean;
+interface SidebarGroupNode {
+    type: 'group';
+    label: string;
+    description?: string;
+    icon?: string;
+    order?: number;
+    children: Record<string, SidebarNode>;
 }
+type SidebarNode = SidebarSurfaceNode | SidebarGroupNode;
 
-/**
- * Base Execution Engine type definitions
- * Core types shared across all Execution Engine resources
- */
-
-/**
- * Immutable execution metadata
- * Represents complete execution identity (who, what, when, where)
- * Shared across ExecutionContext and ExecutionLoggerContext to eliminate field duplication
- */
-interface ExecutionMetadata {
-    executionId: string;
-    organizationId: string;
-    organizationName: string;
-    resourceId: string;
-    userId?: string;
-    sessionId?: string;
-    sessionTurnNumber?: number;
-}
-/**
- * Unified message event type - covers all message types in sessions
- * Replaces separate SessionTurnMessages and AgentActivityEvent mechanisms
- */
-/**
- * Structured action metadata attached to assistant messages.
- * Frontend reads this instead of parsing text prefixes.
- */
-type AssistantAction = {
-    kind: 'navigate';
-    path: string;
-    reason: string;
-} | {
-    kind: 'update_filters';
-    timeRange: string | null;
-    statusFilter: string | null;
-    searchQuery: string | null;
-};
-type MessageEvent = {
-    type: 'user_message';
-    text: string;
-} | {
-    type: 'assistant_message';
-    text: string;
-    _action?: AssistantAction;
-} | {
-    type: 'agent:started';
-} | {
-    type: 'agent:completed';
-} | {
-    type: 'agent:error';
-    error: string;
-} | {
-    type: 'agent:reasoning';
-    iteration: number;
-    reasoning: string;
-} | {
-    type: 'agent:tool_call';
-    toolName: string;
-    args: Record<string, unknown>;
-} | {
-    type: 'agent:tool_result';
-    toolName: string;
-    success: boolean;
-    result?: unknown;
-    error?: string;
-};
-/**
- * Execution context for all resources
- * Unified callback replaces SessionTurnMessages (removed)
- */
-interface ExecutionContext extends ExecutionMetadata {
-    logger: IExecutionLogger;
-    signal?: AbortSignal;
-    onMessageEvent?: (event: MessageEvent) => Promise<void>;
-    /** Called per iteration to write heartbeat + check stall status. Non-fatal if it throws. */
-    onHeartbeat?: () => Promise<void>;
-    aiUsageCollector?: AIUsageCollector;
-    metricsCollector?: MetricsCollector;
-    parentExecutionId?: string;
-    executionDepth: number;
-    credentialName?: string;
-    store: Map<string, unknown>;
-}
-interface Contract {
-    inputSchema: z.ZodSchema;
-    outputSchema?: z.ZodSchema;
-}
-
-/**
- * Tool definitions
- *
- * Tool interface used by agents and workflows.
- * Provides a universal interface for AI systems to interact with tools.
- */
-
-/**
- * Options for tool execution
- * Provides named parameters for better API clarity and extensibility
- */
-interface ToolExecutionOptions {
-    /** Tool input (validated against inputSchema before execution) */
-    input: unknown;
-    /** Execution context with multi-tenant isolation and observability (optional for simple tools, required for platform/integration tools) */
-    executionContext?: ExecutionContext;
-    /** Full iteration context for advanced tools (provides access to memoryManager, toolRegistry, logger, etc.) */
-    iterationContext?: IterationContext;
-    /** Abort signal for timeout/cancellation -- forward to fetch() calls for clean cancellation */
-    signal?: AbortSignal;
-}
-/**
- * Tool interface for AI systems
- *
- * Used by:
- * - Agents: For agentic tool use (reasoning loop selects and executes tools)
- * - Workflows: For workflow step tool invocation (future)
- * - Platform tools: createApprovalTool(), createSchedulerTool()
- * - Integration tools: External API calls (Gmail, Slack, etc.)
- */
-interface Tool {
-    name: string;
-    description: string;
-    inputSchema: z.ZodSchema;
-    outputSchema: z.ZodSchema;
-    execute: (options: ToolExecutionOptions) => Promise<unknown>;
-    timeout?: number;
-}
-
-/**
- * Supported integration types
- *
- * These represent the available integration adapters that can be used with tools.
- * Each integration type corresponds to an adapter implementation.
- *
- * Note: Concrete adapter implementations are deferred until needed.
- * This type provides compile-time safety and auto-completion for tool definitions.
- */
-type IntegrationType = 'gmail' | 'google-sheets' | 'slack' | 'github' | 'linear' | 'attio' | 'airtable' | 'salesforce' | 'hubspot' | 'stripe' | 'twilio' | 'sendgrid' | 'mailgun' | 'zapier' | 'webhook' | 'apify' | 'instantly' | 'resend' | 'signature-api' | 'dropbox' | 'anymailfinder' | 'tomba' | 'millionverifier';
-
-type JsonPrimitive = string | number | boolean | null;
-type JsonValue = JsonPrimitive | JsonValue[] | {
-    [key: string]: JsonValue;
-};
-/** Explicit interface needed to annotate the recursive SystemEntrySchema. */
-interface SystemEntry {
-    id: string;
-    label?: string;
-    title?: string;
-    description?: string;
-    kind?: 'product' | 'operational' | 'platform' | 'diagnostic';
-    parentSystemId?: string;
-    ui?: {
-        path: string;
-        surfaces: string[];
-        icon?: string;
-        order?: number;
-    };
-    lifecycle?: 'draft' | 'beta' | 'active' | 'deprecated' | 'archived';
-    responsibleRoleId?: string;
-    governedByKnowledge?: string[];
-    actions?: {
-        actionId: string;
-        intent: 'exposes' | 'consumes';
-        invocation?: unknown;
-    }[];
-    policies?: string[];
-    drivesGoals?: string[];
-    /** @deprecated Use lifecycle. Accepted for one publish cycle. */
-    status?: 'active' | 'deprecated' | 'archived';
-    path?: string;
-    icon?: string;
-    color?: string;
-    uiPosition?: 'sidebar-primary' | 'sidebar-bottom';
-    enabled?: boolean;
-    devOnly?: boolean;
-    requiresAdmin?: boolean;
-    order: number;
-    config?: Record<string, JsonValue>;
-    ontology?: OntologyScope;
-    systems?: Record<string, SystemEntry>;
-    subsystems?: Record<string, SystemEntry>;
-}
-
-/**
- * Resource Registry type definitions
- */
-
-/**
- * Environment/deployment status for resources
- */
-type ResourceStatus = 'dev' | 'prod';
-/**
- * All resource types in the platform
- * Used as the discriminator field in ResourceDefinition
- */
-type ResourceType = 'agent' | 'workflow' | 'trigger' | 'integration' | 'external' | 'human';
-type ResourceSystemSummary = Pick<SystemEntry, 'id' | 'title' | 'description' | 'kind' | 'lifecycle'>;
-/**
- * Base interface for ALL platform resources
- * Shared by both executable (agents, workflows) and non-executable (triggers, integrations, etc.) resources
- */
-interface ResourceDefinition {
-    /** Unique resource identifier */
-    resourceId: string;
-    /** Display name */
-    name: string;
-    /** Purpose and functionality description */
-    description: string;
-    /** Version for change tracking and evolution */
-    version: string;
-    /** Resource type discriminator */
-    type: ResourceType;
-    /** Environment/deployment status */
-    status: ResourceStatus;
-    /** Graph links to Organization Model nodes */
-    links?: ResourceLink[];
-    /** Infrastructure category for filtering */
-    category?: ResourceCategory;
-    /** Whether the agent supports multi-turn sessions (agents only) */
-    sessionCapable?: boolean;
-    /** Whether the resource is local (monorepo) or remote (externally deployed) */
-    origin?: 'local' | 'remote';
-    /** OM System membership — dot-separated system path (e.g. "sys.lead-gen"), when backed by a Resource descriptor */
-    systemPath?: string;
-    /** Display metadata for the owning OM System */
-    system?: ResourceSystemSummary;
-    /** Governance lifecycle status from the OM Resource descriptor */
-    governanceStatus?: ResourceGovernanceStatus;
-    /** Whether this resource is archived and should be excluded from registration and deployment */
-    archived?: boolean;
-}
-/** Webhook provider identifiers */
-type WebhookProviderType = 'cal-com' | 'stripe' | 'signature-api' | 'instantly' | 'apify' | 'test';
-/** Webhook trigger configuration */
-interface WebhookTriggerConfig {
-    /** Provider identifier */
-    provider: WebhookProviderType;
-    /** Event type for documentation (not used for matching - workflow handles routing) */
-    event?: string;
-    /** Optional filtering (e.g., specific form ID for Fillout) */
-    filter?: Record<string, string>;
-    /** References credential in credentials table for per-org webhook secrets */
-    credentialName?: string;
-}
-/** Schedule trigger configuration */
-interface ScheduleTriggerConfig {
-    /** Cron expression (e.g., '0 6 * * *') */
-    cron: string;
-    /** Optional timezone (default: UTC) */
-    timezone?: string;
-}
-/** Event trigger configuration */
-interface EventTriggerConfig {
-    /** Internal event type */
-    eventType: string;
-    /** Event source */
-    source?: string;
-}
-/** Union of all trigger configs */
-type TriggerConfig = WebhookTriggerConfig | ScheduleTriggerConfig | EventTriggerConfig;
-/**
- * Trigger metadata - entry points that initiate resource execution
- *
- * Triggers represent how executions start: webhooks from external services,
- * scheduled cron jobs, platform events, or manual user actions.
- *
- * BREAKING CHANGES (2025-11-30):
- * - Now extends ResourceDefinition (inherits: resourceId, name, description, version, type, status, links, category)
- * - Field renames: `id` -> `resourceId` (inherited), `type` -> `triggerType`
- * - Relationship rename: `invokes` -> `triggers` (unified vocabulary)
- * - New required fields: `version` (inherited), `type: 'trigger'` (inherited)
- * - triggers object now includes `externalResources` option
- *
- * @example
- * // TriggerDefinition - metadata only
- * {
- *   resourceId: 'trigger-new-order',
- *   type: 'trigger',
- *   triggerType: 'webhook',
- *   name: 'New Order',
- *   description: 'Webhook from Shopify on new orders',
- *   version: '1.0.0',
- *   status: 'prod',
- *   webhookPath: '/webhooks/shopify/orders'
- * }
- *
- * // Relationships declared in ResourceRelationships (not on TriggerDefinition):
- * // relationships: {
- * //   'trigger-new-order': { triggers: { workflows: ['order-fulfillment-workflow'] } }
- * // }
- */
-interface TriggerDefinition extends ResourceDefinition {
-    /** Resource type discriminator (narrowed from base union) */
-    type: 'trigger';
-    /** Trigger mechanism type (renamed from 'type' to avoid collision with base type discriminator) */
-    triggerType: 'webhook' | 'schedule' | 'manual' | 'event';
-    /** Type-specific configuration */
-    config?: TriggerConfig;
-    /** For webhook triggers: path like '/webhooks/shopify/orders' */
-    webhookPath?: string;
-    /** For schedule triggers: cron expression like '0 6 * * *' */
-    schedule?: string;
-    /** For event triggers: event type like 'low-stock-alert' */
-    eventType?: string;
-}
-/**
- * Integration metadata - external service connections
- *
- * References credentials table for actual connection. No connection status
- * stored here (queried at runtime from credentials table).
- *
- * BREAKING CHANGES (2025-11-30):
- * - Now extends ResourceDefinition (inherits: resourceId, name, description, version, type, status, links, category)
- * - Field renames: `id` -> `resourceId` (inherited)
- * - New required field: `status` (inherited) - organizations must add status to all integrations
- * - New required field: `version` (inherited) - organizations must add version to all integrations
- * - New required field: `type: 'integration'` (inherited) - resource type discriminator
- *
- * @example
- * {
- *   resourceId: 'integration-shopify-prod',
- *   type: 'integration',
- *   provider: 'shopify',
- *   credentialName: 'shopify-prod',
- *   name: 'Shopify Production',
- *   description: 'E-commerce platform',
- *   version: '1.0.0',
- *   status: 'prod'
- * }
- */
-interface IntegrationDefinition extends ResourceDefinition {
-    /** Resource type discriminator (narrowed from base union) */
-    type: 'integration';
-    /** OM descriptor that owns canonical identity and governance metadata. */
-    resource?: Extract<ResourceEntry, {
-        kind: 'integration';
-    }>;
-    /** Integration provider type */
-    provider: IntegrationType;
-    /** References credentials table (e.g., 'shopify-prod', 'zendesk-api') */
-    credentialName: string;
-}
-/**
- * Explicit resource relationship declaration
- *
- * Single-direction only - Command View derives reverse relationships.
- * Agents/workflows declare what they trigger and use.
- *
- * @example
- * {
- *   triggers: { workflows: ['order-fulfillment-workflow'] },
- *   uses: { integrations: ['integration-shopify-prod', 'integration-postgres'] }
- * }
- */
-interface RelationshipDeclaration {
-    /** Resources this resource triggers */
-    triggers?: {
-        /** Agent resourceIds this resource triggers */
-        agents?: string[];
-        /** Workflow resourceIds this resource triggers */
-        workflows?: string[];
-    };
-    /** Integrations this resource uses */
-    uses?: {
-        /** Integration IDs this resource uses */
-        integrations?: string[];
-    };
-}
-/**
- * Resource relationships map
- * Maps resourceId to its relationship declarations
- *
- * @example
- * {
- *   'order-processor-agent': {
- *     triggers: { workflows: ['order-fulfillment-workflow'] },
- *     uses: { integrations: ['integration-shopify-prod'] }
- *   }
- * }
- */
-type ResourceRelationships = Record<string, RelationshipDeclaration>;
-/**
- * External platform type
- * Supported third-party automation platforms
- */
-type ExternalPlatform = 'n8n' | 'make' | 'zapier' | 'other';
-/**
- * External automation resource metadata
- *
- * Represents workflows/automations running on third-party platforms
- * (n8n, Make, Zapier, etc.) for visualization in Command View.
- *
- * NOTE: This is metadata ONLY for visualization. No execution logic,
- * no API integration with external platforms, no status syncing.
- *
- * BREAKING CHANGES (2025-11-30):
- * - Now extends ResourceDefinition (inherits: resourceId, name, description, version, type, status, links, category)
- * - Field renames: `id` -> `resourceId` (inherited)
- * - New required field: `version` (inherited) - organizations must add version to all external resources
- * - New required field: `type: 'external'` (inherited) - resource type discriminator
- * - REMOVED FIELD: `triggeredBy` - per relationship-consolidation design, all relationships are forward-only declarations
- *
- * @example
- * {
- *   resourceId: 'external-n8n-order-sync',
- *   type: 'external',
- *   version: '1.0.0',
- *   platform: 'n8n',
- *   name: 'Shopify Order Sync',
- *   description: 'Legacy n8n workflow for syncing Shopify orders',
- *   status: 'prod',
- *   platformUrl: 'https://n8n.client.com/workflow/123',
- *   triggers: { workflows: ['order-fulfillment-workflow'] },
- *   uses: { integrations: ['integration-shopify-prod'] }
- * }
- */
-interface ExternalResourceDefinition extends ResourceDefinition {
-    /** Resource type discriminator (narrowed from base union) */
-    type: 'external';
-    /** Platform type */
-    platform: ExternalPlatform;
-    /** Link to external platform (e.g., n8n workflow editor URL) */
-    platformUrl?: string;
-    /** Platform's internal ID/reference */
-    externalId?: string;
-    /** What this external resource triggers (external -> internal) */
-    triggers?: {
-        /** Elevasis workflow resourceIds this external automation triggers */
-        workflows?: string[];
-        /** Elevasis agent resourceIds this external automation triggers */
-        agents?: string[];
-    };
-    /** Integrations this external resource uses (shared credentials) */
-    uses?: {
-        /** Integration IDs this external automation uses */
-        integrations?: string[];
-    };
-}
-/**
- * Human Checkpoint definition - human decision points in automation
- *
- * Represents where human judgment is deployed in the automation landscape.
- * Tasks with matching command_queue_group are routed to this checkpoint.
- *
- * BREAKING CHANGES (2025-11-30):
- * - Now extends ResourceDefinition (inherits: resourceId, name, description, version, type, status, links, category)
- * - Field renames: `id` -> `resourceId` (inherited)
- * - description is now REQUIRED (was optional) - organizations must add description to all human checkpoints
- * - New required field: `version` (inherited) - organizations must add version to all human checkpoints
- * - New required field: `type: 'human'` (inherited) - resource type discriminator
- *
- * @example
- * {
- *   resourceId: 'sales-approval',
- *   type: 'human',
- *   name: 'Sales Approval Queue',
- *   description: 'High-value order approvals for sales team',
- *   version: '1.0.0',
- *   status: 'prod',
- *   requestedBy: { agents: ['order-processor-agent'] },
- *   routesTo: { agents: ['order-fulfillment-agent'] }
- * }
- */
-interface HumanCheckpointDefinition extends ResourceDefinition {
-    /** Resource type discriminator (narrowed from base union) */
-    type: 'human';
-    /** Resources that create tasks for this checkpoint */
-    requestedBy?: {
-        /** Agent resourceIds that request approval here */
-        agents?: string[];
-        /** Workflow resourceIds that request approval here */
-        workflows?: string[];
-    };
-    /** Resources that receive approved decisions */
-    routesTo?: {
-        /** Agent resourceIds that handle approved tasks */
-        agents?: string[];
-        /** Workflow resourceIds that handle approved tasks */
-        workflows?: string[];
-    };
-}
-
-declare const SurfaceTypeSchema: z.ZodEnum<{
-    dashboard: "dashboard";
-    settings: "settings";
-    graph: "graph";
-    list: "list";
-    page: "page";
-    detail: "detail";
-}>;
-interface SidebarSurfaceNode {
-    type: 'surface';
-    label: string;
-    path: string;
-    surfaceType: z.infer<typeof SurfaceTypeSchema>;
-    description?: string;
-    icon?: string;
-    order?: number;
-    targets?: {
-        systems?: string[];
-        entities?: string[];
-        resources?: string[];
-        actions?: string[];
-    };
-    devOnly?: boolean;
-    requiresAdmin?: boolean;
-}
-interface SidebarGroupNode {
-    type: 'group';
-    label: string;
-    description?: string;
-    icon?: string;
-    order?: number;
-    children: Record<string, SidebarNode>;
-}
-type SidebarNode = SidebarSurfaceNode | SidebarGroupNode;
-
-declare const LinkSchema: z.ZodObject<{
-    nodeId: z.ZodString;
-    kind: z.ZodEnum<{
-        links: "links";
-        affects: "affects";
-        effects: "effects";
-        actions: "actions";
-        reads: "reads";
-        writes: "writes";
-        emits: "emits";
-        triggers: "triggers";
-        uses: "uses";
-        approval: "approval";
-        contains: "contains";
-        references: "references";
-        maps_to: "maps_to";
-        governs: "governs";
-        originates_from: "originates_from";
-        applies_to: "applies_to";
-        uses_catalog: "uses_catalog";
-    }>;
-}, z.core.$strip>;
-type Link = z.infer<typeof LinkSchema>;
+declare const LinkSchema: z.ZodObject<{
+    nodeId: z.ZodString;
+    kind: z.ZodEnum<{
+        links: "links";
+        affects: "affects";
+        effects: "effects";
+        actions: "actions";
+        reads: "reads";
+        writes: "writes";
+        emits: "emits";
+        triggers: "triggers";
+        uses: "uses";
+        approval: "approval";
+        contains: "contains";
+        references: "references";
+        maps_to: "maps_to";
+        governs: "governs";
+        originates_from: "originates_from";
+        applies_to: "applies_to";
+        uses_catalog: "uses_catalog";
+    }>;
+}, z.core.$strip>;
+type Link = z.infer<typeof LinkSchema>;
 
 declare const OrganizationModelSchema$1: z.ZodObject<{
     version: z.ZodDefault<z.ZodLiteral<1>>;
@@ -2225,7 +1665,7 @@ declare const OrganizationModelSchema$1: z.ZodObject<{
             lastModified: string;
         } | undefined;
     }>>;
-    branding: z.ZodObject<{
+    branding: z.ZodDefault<z.ZodObject<{
         organizationName: z.ZodString;
         productName: z.ZodString;
         shortName: z.ZodString;
@@ -2234,7 +1674,7 @@ declare const OrganizationModelSchema$1: z.ZodObject<{
             light: z.ZodOptional<z.ZodString>;
             dark: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
-    }, z.core.$strip>;
+    }, z.core.$strip>>;
     navigation: z.ZodDefault<z.ZodObject<{
         sidebar: z.ZodDefault<z.ZodObject<{
             primary: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodType<SidebarNode, unknown, z.core.$ZodTypeInternals<SidebarNode, unknown>>>>;
@@ -2962,7 +2402,567 @@ declare const OrganizationModelSchema$1: z.ZodObject<{
     }, z.core.$strip>>>>;
 }, z.core.$strip>;
 
-type OrganizationModel$1 = z.infer<typeof OrganizationModelSchema$1>;
+type OrganizationModel$1 = z.infer<typeof OrganizationModelSchema$1>;
+
+/**
+ * MetricsCollector
+ * Tracks execution timing and ROI metrics
+ */
+declare class MetricsCollector {
+    private timings;
+    private durationMs?;
+    /**
+     * Start a timer with a label
+     */
+    startTimer(label: string): void;
+    /**
+     * End a timer and calculate duration
+     * If label is 'execution', stores duration for metrics summary
+     */
+    endTimer(label: string): number | null;
+    /**
+     * Build execution metrics summary with optional ROI calculation
+     */
+    buildExecutionMetrics(metricsConfig?: ResourceMetricsConfig): ExecutionMetricsSummary;
+}
+
+interface BaseAICall {
+    callSequence: number;
+    callType: 'agent-reasoning' | 'agent-completion' | 'workflow-step' | 'tool' | 'other';
+    model: LLMModel;
+    inputTokens: number;
+    outputTokens: number;
+    costUsd: number;
+    latencyMs: number;
+    context?: AICallContext;
+}
+type AICallContext = AgentReasoningContext | AgentCompletionContext | WorkflowStepContext | ToolCallContext | OtherCallContext;
+interface AgentReasoningContext {
+    type: 'agent-reasoning';
+    iteration: number;
+    actionsPlanned?: string[];
+    sessionId?: string;
+    turnNumber?: number;
+}
+interface AgentCompletionContext {
+    type: 'agent-completion';
+    attempt: 1 | 2;
+    validationFailed?: boolean;
+    sessionId?: string;
+    turnNumber?: number;
+}
+interface WorkflowStepContext {
+    type: 'workflow-step';
+    stepId: string;
+    stepName?: string;
+    stepSequence?: number;
+}
+interface ToolCallContext {
+    type: 'tool';
+    toolName: string;
+    parentIteration?: number;
+    parentStepId?: string;
+}
+interface OtherCallContext {
+    type: 'other';
+    description?: string;
+    metadata?: Record<string, unknown>;
+}
+type AICallRecord = BaseAICall;
+/**
+ * Raw LLM usage data returned by adapters
+ * Used as input to AIUsageCollector.record()
+ */
+interface LLMUsageData {
+    model: LLMModel;
+    inputTokens: number;
+    outputTokens: number;
+    latencyMs: number;
+    /** Actual cost from provider in USD (when available, e.g., OpenRouter) */
+    cost?: number;
+}
+interface AIUsageSummary {
+    model: LLMModel;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    totalTokens: number;
+    totalCostUsd: number;
+    callCount: number;
+    calls: AICallRecord[];
+}
+interface ExecutionMetricsSummary {
+    durationMs?: number;
+    automationSavingsUsd?: number;
+}
+interface ResourceMetricsConfig {
+    estimatedManualMinutes: number;
+    hourlyLaborRateUsd: number;
+    confidenceLevel?: 'low' | 'medium' | 'high';
+    notes?: string;
+}
+
+/**
+ * AIUsageCollector
+ * Centralized token tracking that aggregates usage across all LLM calls in an execution
+ */
+declare class AIUsageCollector {
+    private model;
+    private calls;
+    private callSequence;
+    /**
+     * Record a single AI call with usage metrics
+     *
+     * @param usage - Token usage and latency data from LLM adapter
+     * @param callType - Type discriminator (agent-reasoning, tool, etc.)
+     * @param context - Optional typed context specific to callType
+     */
+    record(usage: LLMUsageData, callType?: BaseAICall['callType'], context?: AICallContext): void;
+    /**
+     * Get aggregated summary of all AI calls
+     */
+    getSummary(): AIUsageSummary;
+    /**
+     * Check if any usage has been recorded
+     */
+    hasUsage(): boolean;
+}
+
+/**
+ * Base Execution Engine type definitions
+ * Core types shared across all Execution Engine resources
+ */
+
+/**
+ * Immutable execution metadata
+ * Represents complete execution identity (who, what, when, where)
+ * Shared across ExecutionContext and ExecutionLoggerContext to eliminate field duplication
+ */
+interface ExecutionMetadata {
+    executionId: string;
+    organizationId: string;
+    organizationName: string;
+    resourceId: string;
+    userId?: string;
+    sessionId?: string;
+    sessionTurnNumber?: number;
+}
+/**
+ * Unified message event type - covers all message types in sessions
+ * Replaces separate SessionTurnMessages and AgentActivityEvent mechanisms
+ */
+/**
+ * Structured action metadata attached to assistant messages.
+ * Frontend reads this instead of parsing text prefixes.
+ */
+type AssistantAction = {
+    kind: 'navigate';
+    path: string;
+    reason: string;
+} | {
+    kind: 'update_filters';
+    timeRange: string | null;
+    statusFilter: string | null;
+    searchQuery: string | null;
+};
+type MessageEvent = {
+    type: 'user_message';
+    text: string;
+} | {
+    type: 'assistant_message';
+    text: string;
+    _action?: AssistantAction;
+} | {
+    type: 'agent:started';
+} | {
+    type: 'agent:completed';
+} | {
+    type: 'agent:error';
+    error: string;
+} | {
+    type: 'agent:reasoning';
+    iteration: number;
+    reasoning: string;
+} | {
+    type: 'agent:tool_call';
+    toolName: string;
+    args: Record<string, unknown>;
+} | {
+    type: 'agent:tool_result';
+    toolName: string;
+    success: boolean;
+    result?: unknown;
+    error?: string;
+};
+/**
+ * Execution context for all resources
+ * Unified callback replaces SessionTurnMessages (removed)
+ */
+interface ExecutionContext extends ExecutionMetadata {
+    logger: IExecutionLogger;
+    signal?: AbortSignal;
+    onMessageEvent?: (event: MessageEvent) => Promise<void>;
+    /** Called per iteration to write heartbeat + check stall status. Non-fatal if it throws. */
+    onHeartbeat?: () => Promise<void>;
+    aiUsageCollector?: AIUsageCollector;
+    metricsCollector?: MetricsCollector;
+    parentExecutionId?: string;
+    executionDepth: number;
+    credentialName?: string;
+    store: Map<string, unknown>;
+}
+interface Contract {
+    inputSchema: z.ZodSchema;
+    outputSchema?: z.ZodSchema;
+}
+
+/**
+ * Tool definitions
+ *
+ * Tool interface used by agents and workflows.
+ * Provides a universal interface for AI systems to interact with tools.
+ */
+
+/**
+ * Options for tool execution
+ * Provides named parameters for better API clarity and extensibility
+ */
+interface ToolExecutionOptions {
+    /** Tool input (validated against inputSchema before execution) */
+    input: unknown;
+    /** Execution context with multi-tenant isolation and observability (optional for simple tools, required for platform/integration tools) */
+    executionContext?: ExecutionContext;
+    /** Full iteration context for advanced tools (provides access to memoryManager, toolRegistry, logger, etc.) */
+    iterationContext?: IterationContext;
+    /** Abort signal for timeout/cancellation -- forward to fetch() calls for clean cancellation */
+    signal?: AbortSignal;
+}
+/**
+ * Tool interface for AI systems
+ *
+ * Used by:
+ * - Agents: For agentic tool use (reasoning loop selects and executes tools)
+ * - Workflows: For workflow step tool invocation (future)
+ * - Platform tools: createApprovalTool(), createSchedulerTool()
+ * - Integration tools: External API calls (Gmail, Slack, etc.)
+ */
+interface Tool {
+    name: string;
+    description: string;
+    inputSchema: z.ZodSchema;
+    outputSchema: z.ZodSchema;
+    execute: (options: ToolExecutionOptions) => Promise<unknown>;
+    timeout?: number;
+}
+
+/**
+ * Supported integration types
+ *
+ * These represent the available integration adapters that can be used with tools.
+ * Each integration type corresponds to an adapter implementation.
+ *
+ * Note: Concrete adapter implementations are deferred until needed.
+ * This type provides compile-time safety and auto-completion for tool definitions.
+ */
+type IntegrationType = 'gmail' | 'google-sheets' | 'slack' | 'github' | 'linear' | 'attio' | 'airtable' | 'salesforce' | 'hubspot' | 'stripe' | 'twilio' | 'sendgrid' | 'mailgun' | 'zapier' | 'webhook' | 'apify' | 'instantly' | 'resend' | 'signature-api' | 'dropbox' | 'anymailfinder' | 'tomba' | 'millionverifier';
+
+/**
+ * Resource Registry type definitions
+ */
+
+/**
+ * Environment/deployment status for resources
+ */
+type ResourceStatus = 'dev' | 'prod';
+/**
+ * All resource types in the platform
+ * Used as the discriminator field in ResourceDefinition
+ */
+type ResourceType = 'agent' | 'workflow' | 'trigger' | 'integration' | 'external' | 'human';
+type ResourceSystemSummary = Pick<SystemEntry, 'id' | 'title' | 'description' | 'kind' | 'lifecycle'>;
+/**
+ * Base interface for ALL platform resources
+ * Shared by both executable (agents, workflows) and non-executable (triggers, integrations, etc.) resources
+ */
+interface ResourceDefinition {
+    /** Unique resource identifier */
+    resourceId: string;
+    /** Display name */
+    name: string;
+    /** Purpose and functionality description */
+    description: string;
+    /** Version for change tracking and evolution */
+    version: string;
+    /** Resource type discriminator */
+    type: ResourceType;
+    /** Environment/deployment status */
+    status: ResourceStatus;
+    /** Graph links to Organization Model nodes */
+    links?: ResourceLink[];
+    /** Infrastructure category for filtering */
+    category?: ResourceCategory;
+    /** Whether the agent supports multi-turn sessions (agents only) */
+    sessionCapable?: boolean;
+    /** Whether the resource is local (monorepo) or remote (externally deployed) */
+    origin?: 'local' | 'remote';
+    /** OM System membership — dot-separated system path (e.g. "sys.lead-gen"), when backed by a Resource descriptor */
+    systemPath?: string;
+    /** Display metadata for the owning OM System */
+    system?: ResourceSystemSummary;
+    /** Governance lifecycle status from the OM Resource descriptor */
+    governanceStatus?: ResourceGovernanceStatus;
+    /** Whether this resource is archived and should be excluded from registration and deployment */
+    archived?: boolean;
+}
+/** Webhook provider identifiers */
+type WebhookProviderType = 'cal-com' | 'stripe' | 'signature-api' | 'instantly' | 'apify' | 'test';
+/** Webhook trigger configuration */
+interface WebhookTriggerConfig {
+    /** Provider identifier */
+    provider: WebhookProviderType;
+    /** Event type for documentation (not used for matching - workflow handles routing) */
+    event?: string;
+    /** Optional filtering (e.g., specific form ID for Fillout) */
+    filter?: Record<string, string>;
+    /** References credential in credentials table for per-org webhook secrets */
+    credentialName?: string;
+}
+/** Schedule trigger configuration */
+interface ScheduleTriggerConfig {
+    /** Cron expression (e.g., '0 6 * * *') */
+    cron: string;
+    /** Optional timezone (default: UTC) */
+    timezone?: string;
+}
+/** Event trigger configuration */
+interface EventTriggerConfig {
+    /** Internal event type */
+    eventType: string;
+    /** Event source */
+    source?: string;
+}
+/** Union of all trigger configs */
+type TriggerConfig = WebhookTriggerConfig | ScheduleTriggerConfig | EventTriggerConfig;
+/**
+ * Trigger metadata - entry points that initiate resource execution
+ *
+ * Triggers represent how executions start: webhooks from external services,
+ * scheduled cron jobs, platform events, or manual user actions.
+ *
+ * BREAKING CHANGES (2025-11-30):
+ * - Now extends ResourceDefinition (inherits: resourceId, name, description, version, type, status, links, category)
+ * - Field renames: `id` -> `resourceId` (inherited), `type` -> `triggerType`
+ * - Relationship rename: `invokes` -> `triggers` (unified vocabulary)
+ * - New required fields: `version` (inherited), `type: 'trigger'` (inherited)
+ * - triggers object now includes `externalResources` option
+ *
+ * @example
+ * // TriggerDefinition - metadata only
+ * {
+ *   resourceId: 'trigger-new-order',
+ *   type: 'trigger',
+ *   triggerType: 'webhook',
+ *   name: 'New Order',
+ *   description: 'Webhook from Shopify on new orders',
+ *   version: '1.0.0',
+ *   status: 'prod',
+ *   webhookPath: '/webhooks/shopify/orders'
+ * }
+ *
+ * // Relationships declared in ResourceRelationships (not on TriggerDefinition):
+ * // relationships: {
+ * //   'trigger-new-order': { triggers: { workflows: ['order-fulfillment-workflow'] } }
+ * // }
+ */
+interface TriggerDefinition extends ResourceDefinition {
+    /** Resource type discriminator (narrowed from base union) */
+    type: 'trigger';
+    /** Trigger mechanism type (renamed from 'type' to avoid collision with base type discriminator) */
+    triggerType: 'webhook' | 'schedule' | 'manual' | 'event';
+    /** Type-specific configuration */
+    config?: TriggerConfig;
+    /** For webhook triggers: path like '/webhooks/shopify/orders' */
+    webhookPath?: string;
+    /** For schedule triggers: cron expression like '0 6 * * *' */
+    schedule?: string;
+    /** For event triggers: event type like 'low-stock-alert' */
+    eventType?: string;
+}
+/**
+ * Integration metadata - external service connections
+ *
+ * References credentials table for actual connection. No connection status
+ * stored here (queried at runtime from credentials table).
+ *
+ * BREAKING CHANGES (2025-11-30):
+ * - Now extends ResourceDefinition (inherits: resourceId, name, description, version, type, status, links, category)
+ * - Field renames: `id` -> `resourceId` (inherited)
+ * - New required field: `status` (inherited) - organizations must add status to all integrations
+ * - New required field: `version` (inherited) - organizations must add version to all integrations
+ * - New required field: `type: 'integration'` (inherited) - resource type discriminator
+ *
+ * @example
+ * {
+ *   resourceId: 'integration-shopify-prod',
+ *   type: 'integration',
+ *   provider: 'shopify',
+ *   credentialName: 'shopify-prod',
+ *   name: 'Shopify Production',
+ *   description: 'E-commerce platform',
+ *   version: '1.0.0',
+ *   status: 'prod'
+ * }
+ */
+interface IntegrationDefinition extends ResourceDefinition {
+    /** Resource type discriminator (narrowed from base union) */
+    type: 'integration';
+    /** OM descriptor that owns canonical identity and governance metadata. */
+    resource?: Extract<ResourceEntry, {
+        kind: 'integration';
+    }>;
+    /** Integration provider type */
+    provider: IntegrationType;
+    /** References credentials table (e.g., 'shopify-prod', 'zendesk-api') */
+    credentialName: string;
+}
+/**
+ * Explicit resource relationship declaration
+ *
+ * Single-direction only - Command View derives reverse relationships.
+ * Agents/workflows declare what they trigger and use.
+ *
+ * @example
+ * {
+ *   triggers: { workflows: ['order-fulfillment-workflow'] },
+ *   uses: { integrations: ['integration-shopify-prod', 'integration-postgres'] }
+ * }
+ */
+interface RelationshipDeclaration {
+    /** Resources this resource triggers */
+    triggers?: {
+        /** Agent resourceIds this resource triggers */
+        agents?: string[];
+        /** Workflow resourceIds this resource triggers */
+        workflows?: string[];
+    };
+    /** Integrations this resource uses */
+    uses?: {
+        /** Integration IDs this resource uses */
+        integrations?: string[];
+    };
+}
+/**
+ * Resource relationships map
+ * Maps resourceId to its relationship declarations
+ *
+ * @example
+ * {
+ *   'order-processor-agent': {
+ *     triggers: { workflows: ['order-fulfillment-workflow'] },
+ *     uses: { integrations: ['integration-shopify-prod'] }
+ *   }
+ * }
+ */
+type ResourceRelationships = Record<string, RelationshipDeclaration>;
+/**
+ * External platform type
+ * Supported third-party automation platforms
+ */
+type ExternalPlatform = 'n8n' | 'make' | 'zapier' | 'other';
+/**
+ * External automation resource metadata
+ *
+ * Represents workflows/automations running on third-party platforms
+ * (n8n, Make, Zapier, etc.) for visualization in Command View.
+ *
+ * NOTE: This is metadata ONLY for visualization. No execution logic,
+ * no API integration with external platforms, no status syncing.
+ *
+ * BREAKING CHANGES (2025-11-30):
+ * - Now extends ResourceDefinition (inherits: resourceId, name, description, version, type, status, links, category)
+ * - Field renames: `id` -> `resourceId` (inherited)
+ * - New required field: `version` (inherited) - organizations must add version to all external resources
+ * - New required field: `type: 'external'` (inherited) - resource type discriminator
+ * - REMOVED FIELD: `triggeredBy` - per relationship-consolidation design, all relationships are forward-only declarations
+ *
+ * @example
+ * {
+ *   resourceId: 'external-n8n-order-sync',
+ *   type: 'external',
+ *   version: '1.0.0',
+ *   platform: 'n8n',
+ *   name: 'Shopify Order Sync',
+ *   description: 'Legacy n8n workflow for syncing Shopify orders',
+ *   status: 'prod',
+ *   platformUrl: 'https://n8n.client.com/workflow/123',
+ *   triggers: { workflows: ['order-fulfillment-workflow'] },
+ *   uses: { integrations: ['integration-shopify-prod'] }
+ * }
+ */
+interface ExternalResourceDefinition extends ResourceDefinition {
+    /** Resource type discriminator (narrowed from base union) */
+    type: 'external';
+    /** Platform type */
+    platform: ExternalPlatform;
+    /** Link to external platform (e.g., n8n workflow editor URL) */
+    platformUrl?: string;
+    /** Platform's internal ID/reference */
+    externalId?: string;
+    /** What this external resource triggers (external -> internal) */
+    triggers?: {
+        /** Elevasis workflow resourceIds this external automation triggers */
+        workflows?: string[];
+        /** Elevasis agent resourceIds this external automation triggers */
+        agents?: string[];
+    };
+    /** Integrations this external resource uses (shared credentials) */
+    uses?: {
+        /** Integration IDs this external automation uses */
+        integrations?: string[];
+    };
+}
+/**
+ * Human Checkpoint definition - human decision points in automation
+ *
+ * Represents where human judgment is deployed in the automation landscape.
+ * Tasks with matching command_queue_group are routed to this checkpoint.
+ *
+ * BREAKING CHANGES (2025-11-30):
+ * - Now extends ResourceDefinition (inherits: resourceId, name, description, version, type, status, links, category)
+ * - Field renames: `id` -> `resourceId` (inherited)
+ * - description is now REQUIRED (was optional) - organizations must add description to all human checkpoints
+ * - New required field: `version` (inherited) - organizations must add version to all human checkpoints
+ * - New required field: `type: 'human'` (inherited) - resource type discriminator
+ *
+ * @example
+ * {
+ *   resourceId: 'sales-approval',
+ *   type: 'human',
+ *   name: 'Sales Approval Queue',
+ *   description: 'High-value order approvals for sales team',
+ *   version: '1.0.0',
+ *   status: 'prod',
+ *   requestedBy: { agents: ['order-processor-agent'] },
+ *   routesTo: { agents: ['order-fulfillment-agent'] }
+ * }
+ */
+interface HumanCheckpointDefinition extends ResourceDefinition {
+    /** Resource type discriminator (narrowed from base union) */
+    type: 'human';
+    /** Resources that create tasks for this checkpoint */
+    requestedBy?: {
+        /** Agent resourceIds that request approval here */
+        agents?: string[];
+        /** Workflow resourceIds that request approval here */
+        workflows?: string[];
+    };
+    /** Resources that receive approved decisions */
+    routesTo?: {
+        /** Agent resourceIds that handle approved tasks */
+        agents?: string[];
+        /** Workflow resourceIds that handle approved tasks */
+        workflows?: string[];
+    };
+}
 
 declare const ResourceCategorySchema: z.ZodEnum<{
     diagnostic: "diagnostic";
@@ -3089,670 +3089,7 @@ declare const IntegrationResourceEntrySchema = ResourceEntryBaseSchema.extend({
   provider: z.string().trim().min(1).max(100)
 })
 
-declare const OrganizationModelSchema = OrganizationModelSchemaBase.superRefine((model, ctx) => {
-  // Collect ALL system entries recursively — top-level systems plus any nested subsystems.
-  // Wave 2 canonical OM authors nested subsystems (e.g. sys → subsystems → 'lead-gen' with id
-  // 'sys.lead-gen'). Resource systemPath cross-refs must resolve against the full flattened set.
-  type SystemWithPath = { path: string; schemaPath: Array<string | number>; system: SystemEntry }
-
-  function collectAllSystems(
-    systems: Record<string, SystemEntry>,
-    prefix = '',
-    schemaPath: Array<string | number> = ['systems']
-  ): SystemWithPath[] {
-    const result: SystemWithPath[] = []
-    for (const [key, system] of Object.entries(systems)) {
-      const path = prefix ? `${prefix}.${key}` : key
-      const currentSchemaPath = [...schemaPath, key]
-      result.push({ path, schemaPath: currentSchemaPath, system })
-      const childSystems = system.systems ?? system.subsystems
-      if (childSystems !== undefined) {
-        result.push(
-          ...collectAllSystems(childSystems, path, [
-            ...currentSchemaPath,
-            system.systems !== undefined ? 'systems' : 'subsystems'
-          ])
-        )
-      }
-    }
-    return result
-  }
-
-  const allSystems = collectAllSystems(model.systems)
-  const systemsById = new Map<string, SystemEntry>()
-  for (const { path, system } of allSystems) {
-    systemsById.set(path, system)
-    systemsById.set(system.id, system)
-  }
-
-  const systemIdsByEffectivePath = new Map<string, string>()
-  allSystems.forEach(({ path, schemaPath, system }) => {
-    if (system.parentSystemId !== undefined && !systemsById.has(system.parentSystemId)) {
-      addIssue(
-        ctx,
-        [...schemaPath, 'parentSystemId'],
-        `System "${system.id}" references unknown parent "${system.parentSystemId}"`
-      )
-    }
-
-    const hasChildren =
-      Object.keys(system.systems ?? system.subsystems ?? {}).length > 0 ||
-      allSystems.some(
-        (candidate) => candidate.path.startsWith(`${path}.`) && !candidate.path.slice(path.length + 1).includes('.')
-      )
-    const contributesRoutePath = system.ui?.path !== undefined || system.path !== undefined || !hasChildren
-    if (contributesRoutePath) {
-      const effectivePath = system.ui?.path ?? system.path ?? defaultSystemPathFor(path)
-      const existingSystemId = systemIdsByEffectivePath.get(effectivePath)
-      if (existingSystemId !== undefined) {
-        addIssue(
-          ctx,
-          [...schemaPath, system.ui?.path !== undefined ? 'ui' : 'path'],
-          `System "${path}" effective path "${effectivePath}" duplicates system "${existingSystemId}"`
-        )
-      } else {
-        systemIdsByEffectivePath.set(effectivePath, path)
-      }
-    }
-
-    if (hasChildren && isLifecycleEnabled(system.lifecycle, system.enabled)) {
-      const hasEnabledDescendant =
-        Object.values(system.systems ?? system.subsystems ?? {}).some((candidate) =>
-          isLifecycleEnabled(candidate.lifecycle, candidate.enabled)
-        ) ||
-        allSystems.some(
-          (candidate) =>
-            candidate.path.startsWith(`${path}.`) &&
-            !candidate.path.slice(path.length + 1).includes('.') &&
-            isLifecycleEnabled(candidate.system.lifecycle, candidate.system.enabled)
-        )
-      if (!hasEnabledDescendant) {
-        addIssue(ctx, [...schemaPath, 'lifecycle'], `System "${path}" is active but has no active descendants`)
-      }
-    }
-  })
-
-  allSystems.forEach(({ schemaPath, system }) => {
-    const visited = new Set<string>()
-    let currentParentId = system.parentSystemId
-
-    while (currentParentId !== undefined) {
-      if (currentParentId === system.id || visited.has(currentParentId)) {
-        addIssue(ctx, [...schemaPath, 'parentSystemId'], `System "${system.id}" has a parent cycle`)
-        return
-      }
-
-      visited.add(currentParentId)
-      currentParentId = systemsById.get(currentParentId)?.parentSystemId
-    }
-  })
-
-  type CollectedSidebarSurface = {
-    id: string
-    node: Extract<SidebarNode, { type: 'surface' }>
-    path: Array<string | number>
-  }
-
-  function normalizeRoutePath(path: string): string {
-    return path.length > 1 ? path.replace(/\/+$/, '') : path
-  }
-
-  const sidebarNodeIds = new Map<string, Array<string | number>>()
-  const sidebarSurfacePaths = new Map<string, string>()
-  const sidebarSurfaces: CollectedSidebarSurface[] = []
-
-  function collectSidebarNodes(nodes: Record<string, SidebarNode>, schemaPath: Array<string | number>): void {
-    Object.entries(nodes).forEach(([nodeId, node]) => {
-      const nodePath = [...schemaPath, nodeId]
-      const existingNodePath = sidebarNodeIds.get(nodeId)
-      if (existingNodePath !== undefined) {
-        addIssue(ctx, nodePath, `Sidebar node id "${nodeId}" duplicates another sidebar node`)
-      } else {
-        sidebarNodeIds.set(nodeId, nodePath)
-      }
-
-      if (node.type === 'group') {
-        collectSidebarNodes(node.children, [...nodePath, 'children'])
-        return
-      }
-
-      sidebarSurfaces.push({ id: nodeId, node, path: nodePath })
-      const normalizedPath = normalizeRoutePath(node.path)
-      const existingSurfaceId = sidebarSurfacePaths.get(normalizedPath)
-      if (existingSurfaceId !== undefined) {
-        addIssue(
-          ctx,
-          [...nodePath, 'path'],
-          `Sidebar surface path "${node.path}" duplicates surface "${existingSurfaceId}"`
-        )
-      } else {
-        sidebarSurfacePaths.set(normalizedPath, nodeId)
-      }
-
-      node.targets?.systems?.forEach((systemId, systemIndex) => {
-        if (!systemsById.has(systemId)) {
-          addIssue(
-            ctx,
-            [...nodePath, 'targets', 'systems', systemIndex],
-            `Sidebar surface "${nodeId}" references unknown system "${systemId}"`
-          )
-        }
-      })
-    })
-  }
-
-  collectSidebarNodes(model.navigation.sidebar.primary, ['navigation', 'sidebar', 'primary'])
-  collectSidebarNodes(model.navigation.sidebar.bottom, ['navigation', 'sidebar', 'bottom'])
-
-  // Offerings -> CustomerSegment cross-ref: targetSegmentIds must resolve
-  const segmentsById = new Map(Object.entries(model.customers))
-  Object.values(model.offerings).forEach((product) => {
-    product.targetSegmentIds.forEach((segmentId, segmentIndex) => {
-      if (!segmentsById.has(segmentId)) {
-        addIssue(
-          ctx,
-          ['offerings', product.id, 'targetSegmentIds', segmentIndex],
-          `Product "${product.id}" references unknown customer segment "${segmentId}"`
-        )
-      }
-    })
-
-    // Offerings -> System cross-ref: deliveryFeatureId must resolve (when present)
-    if (product.deliveryFeatureId !== undefined && !systemsById.has(product.deliveryFeatureId)) {
-      addIssue(
-        ctx,
-        ['offerings', product.id, 'deliveryFeatureId'],
-        `Product "${product.id}" references unknown delivery system "${product.deliveryFeatureId}"`
-      )
-    }
-  })
-
-  // Goals -> period-range validation: periodEnd must be strictly after periodStart
-  Object.values(model.goals).forEach((objective) => {
-    if (objective.periodEnd <= objective.periodStart) {
-      addIssue(
-        ctx,
-        ['goals', objective.id, 'periodEnd'],
-        `Goal "${objective.id}" has periodEnd "${objective.periodEnd}" which must be strictly after periodStart "${objective.periodStart}"`
-      )
-    }
-  })
-
-  const goalsById = new Map(Object.entries(model.goals))
-  // Phase 4: knowledge is now a flat Record<id, OrgKnowledgeNode> — no .nodes array
-  const knowledgeById = new Map(Object.entries(model.knowledge))
-  const actionsById = new Map(Object.entries(model.actions))
-  const entitiesById = new Map(Object.entries(model.entities))
-  const policiesById = new Map(Object.entries(model.policies))
-
-  sidebarSurfaces.forEach(({ id, node, path }) => {
-    node.targets?.entities?.forEach((entityId, entityIndex) => {
-      if (!entitiesById.has(entityId)) {
-        addIssue(
-          ctx,
-          [...path, 'targets', 'entities', entityIndex],
-          `Sidebar surface "${id}" references unknown entity "${entityId}"`
-        )
-      }
-    })
-
-    node.targets?.actions?.forEach((actionId, actionIndex) => {
-      if (!actionsById.has(actionId)) {
-        addIssue(
-          ctx,
-          [...path, 'targets', 'actions', actionIndex],
-          `Sidebar surface "${id}" references unknown action "${actionId}"`
-        )
-      }
-    })
-  })
-
-  Object.values(model.entities).forEach((entity) => {
-    if (!systemsById.has(entity.ownedBySystemId)) {
-      addIssue(
-        ctx,
-        ['entities', entity.id, 'ownedBySystemId'],
-        `Entity "${entity.id}" references unknown ownedBySystemId "${entity.ownedBySystemId}"`
-      )
-    }
-
-    entity.links?.forEach((link, linkIndex) => {
-      if (!entitiesById.has(link.toEntity)) {
-        addIssue(
-          ctx,
-          ['entities', entity.id, 'links', linkIndex, 'toEntity'],
-          `Entity "${entity.id}" links to unknown entity "${link.toEntity}"`
-        )
-      }
-    })
-  })
-
-  // Roles -> reportsToId cross-ref: each reportsToId must resolve to another role in the same collection
-  const rolesById = new Map(Object.entries(model.roles))
-  Object.values(model.roles).forEach((role) => {
-    if (role.reportsToId !== undefined && !rolesById.has(role.reportsToId)) {
-      addIssue(
-        ctx,
-        ['roles', role.id, 'reportsToId'],
-        `Role "${role.id}" references unknown reportsToId "${role.reportsToId}"`
-      )
-    }
-  })
-
-  Object.values(model.roles).forEach((role) => {
-    const visited = new Set<string>()
-    let currentReportsToId = role.reportsToId
-
-    while (currentReportsToId !== undefined) {
-      if (currentReportsToId === role.id || visited.has(currentReportsToId)) {
-        addIssue(ctx, ['roles', role.id, 'reportsToId'], `Role "${role.id}" has a reportsToId cycle`)
-        return
-      }
-
-      visited.add(currentReportsToId)
-      currentReportsToId = rolesById.get(currentReportsToId)?.reportsToId
-    }
-  })
-
-  Object.values(model.roles).forEach((role) => {
-    role.responsibleFor?.forEach((systemId, systemIndex) => {
-      if (!systemsById.has(systemId)) {
-        addIssue(
-          ctx,
-          ['roles', role.id, 'responsibleFor', systemIndex],
-          `Role "${role.id}" references unknown responsibleFor system "${systemId}"`
-        )
-      }
-    })
-  })
-
-  allSystems.forEach(({ schemaPath, system }) => {
-    if (system.responsibleRoleId !== undefined && !rolesById.has(system.responsibleRoleId)) {
-      addIssue(
-        ctx,
-        [...schemaPath, 'responsibleRoleId'],
-        `System "${system.id}" references unknown responsibleRoleId "${system.responsibleRoleId}"`
-      )
-    }
-
-    system.governedByKnowledge?.forEach((nodeId, nodeIndex) => {
-      if (!knowledgeById.has(nodeId)) {
-        addIssue(
-          ctx,
-          [...schemaPath, 'governedByKnowledge', nodeIndex],
-          `System "${system.id}" references unknown knowledge node "${nodeId}"`
-        )
-      }
-    })
-
-    system.drivesGoals?.forEach((goalId, goalIndex) => {
-      if (!goalsById.has(goalId)) {
-        addIssue(
-          ctx,
-          [...schemaPath, 'drivesGoals', goalIndex],
-          `System "${system.id}" references unknown goal "${goalId}"`
-        )
-      }
-    })
-
-    system.actions?.forEach((actionRef, actionIndex) => {
-      if (!actionsById.has(actionRef.actionId)) {
-        addIssue(
-          ctx,
-          [...schemaPath, 'actions', actionIndex, 'actionId'],
-          `System "${system.id}" references unknown action "${actionRef.actionId}"`
-        )
-      }
-    })
-
-    system.policies?.forEach((policyId, policyIndex) => {
-      if (!policiesById.has(policyId)) {
-        addIssue(
-          ctx,
-          [...schemaPath, 'policies', policyIndex],
-          `System "${system.id}" references unknown policy "${policyId}"`
-        )
-      }
-    })
-  })
-
-  Object.values(model.actions).forEach((action) => {
-    action.affects?.forEach((entityId, entityIndex) => {
-      if (!entitiesById.has(entityId)) {
-        addIssue(
-          ctx,
-          ['actions', action.id, 'affects', entityIndex],
-          `Action "${action.id}" affects unknown entity "${entityId}"`
-        )
-      }
-    })
-  })
-
-  // Phase 4: sales / prospecting / projects compound-domain entity cross-ref checks removed.
-  // Those entity bindings now live in System.ontology catalog scopes.
-
-  const resourcesById = new Map(Object.entries(model.resources))
-  sidebarSurfaces.forEach(({ id, node, path }) => {
-    node.targets?.resources?.forEach((resourceId, resourceIndex) => {
-      if (!resourcesById.has(resourceId)) {
-        addIssue(
-          ctx,
-          [...path, 'targets', 'resources', resourceIndex],
-          `Sidebar surface "${id}" references unknown resource "${resourceId}"`
-        )
-      }
-    })
-  })
-  const actionIds = new Set(Object.keys(model.actions))
-  const offeringsById = new Map(Object.entries(model.offerings))
-  const ontologyCompilation = compileOrganizationOntology(model)
-  const stageIds = new Set<string>()
-  for (const catalog of Object.values(ontologyCompilation.ontology.catalogTypes)) {
-    if (catalog.kind !== 'stage') continue
-    for (const stageId of Object.keys(catalog.entries ?? {})) {
-      stageIds.add(stageId)
-    }
-  }
-  const ontologyIndexByKind = {
-    object: ontologyCompilation.ontology.objectTypes,
-    link: ontologyCompilation.ontology.linkTypes,
-    action: ontologyCompilation.ontology.actionTypes,
-    catalog: ontologyCompilation.ontology.catalogTypes,
-    event: ontologyCompilation.ontology.eventTypes,
-    interface: ontologyCompilation.ontology.interfaceTypes,
-    'value-type': ontologyCompilation.ontology.valueTypes,
-    property: ontologyCompilation.ontology.sharedProperties,
-    group: ontologyCompilation.ontology.groups,
-    surface: ontologyCompilation.ontology.surfaces
-  } satisfies Record<OntologyKind, Record<string, unknown>>
-  const ontologyIds = new Set(Object.values(ontologyIndexByKind).flatMap((index) => Object.keys(index)))
-
-  function topologyTargetExists(ref: OmTopologyNodeRef): boolean {
-    if (ref.kind === 'system') return systemsById.has(ref.id)
-    if (ref.kind === 'resource') return resourcesById.has(ref.id)
-    if (ref.kind === 'ontology') return ontologyIds.has(ref.id)
-    if (ref.kind === 'policy') return policiesById.has(ref.id)
-    if (ref.kind === 'role') return rolesById.has(ref.id)
-
-    // Trigger, human checkpoint, and external resource refs are projected
-    // topology nodes during the bridge period; their owning runtime indexes are
-    // validated by deployment projection in later waves.
-    return true
-  }
-
-  Object.entries(model.topology.relationships).forEach(([relationshipId, relationship]) => {
-    ;(['from', 'to'] as const).forEach((side) => {
-      const ref = relationship[side]
-      if (topologyTargetExists(ref)) return
-
-      addIssue(
-        ctx,
-        ['topology', 'relationships', relationshipId, side],
-        `Topology relationship "${relationshipId}" ${side} references unknown ${ref.kind} "${ref.id}"`
-      )
-    })
-  })
-
-  const ontologyReferenceKeyKinds = {
-    valueType: 'value-type',
-    catalogType: 'catalog',
-    objectType: 'object',
-    eventType: 'event',
-    actionType: 'action',
-    linkType: 'link',
-    interfaceType: 'interface',
-    propertyType: 'property',
-    groupType: 'group',
-    surfaceType: 'surface',
-    stepCatalog: 'catalog'
-  } satisfies Record<string, OntologyKind>
-
-  function validateKnownOntologyReferences(
-    ownerId: string,
-    value: unknown,
-    path: Array<string | number>,
-    seen = new WeakSet<object>()
-  ): void {
-    if (Array.isArray(value)) {
-      value.forEach((entry, index) => validateKnownOntologyReferences(ownerId, entry, [...path, index], seen))
-      return
-    }
-
-    if (!isRecord(value)) return
-    if (seen.has(value)) return
-    seen.add(value)
-
-    Object.entries(value).forEach(([key, entry]) => {
-      const expectedKind = ontologyReferenceKeyKinds[key as keyof typeof ontologyReferenceKeyKinds]
-      if (expectedKind !== undefined) {
-        if (typeof entry !== 'string') {
-          addIssue(ctx, [...path, key], `Ontology record "${ownerId}" ${key} must be an ontology ID string`)
-        } else if (ontologyIndexByKind[expectedKind][entry] === undefined) {
-          addIssue(
-            ctx,
-            [...path, key],
-            `Ontology record "${ownerId}" ${key} references unknown ${expectedKind} ontology ID "${entry}"`
-          )
-        }
-      }
-
-      validateKnownOntologyReferences(ownerId, entry, [...path, key], seen)
-    })
-  }
-
-  for (const { id, record } of listResolvedOntologyRecords(ontologyCompilation.ontology)) {
-    validateKnownOntologyReferences(id, record, record.origin.path)
-  }
-
-  Object.values(model.policies).forEach((policy) => {
-    policy.appliesTo.systemIds.forEach((systemId, systemIndex) => {
-      if (!systemsById.has(systemId)) {
-        addIssue(
-          ctx,
-          ['policies', policy.id, 'appliesTo', 'systemIds', systemIndex],
-          `Policy "${policy.id}" applies to unknown system "${systemId}"`
-        )
-      }
-    })
-
-    policy.appliesTo.actionIds.forEach((actionId, actionIndex) => {
-      if (!actionsById.has(actionId)) {
-        addIssue(
-          ctx,
-          ['policies', policy.id, 'appliesTo', 'actionIds', actionIndex],
-          `Policy "${policy.id}" applies to unknown action "${actionId}"`
-        )
-      }
-    })
-
-    policy.actions.forEach((action, actionIndex) => {
-      if (action.kind === 'invoke-action' && !actionsById.has(action.actionId)) {
-        addIssue(
-          ctx,
-          ['policies', policy.id, 'actions', actionIndex, 'actionId'],
-          `Policy "${policy.id}" invokes unknown action "${action.actionId}"`
-        )
-      }
-      if (
-        (action.kind === 'notify-role' || action.kind === 'require-approval') &&
-        action.roleId !== undefined &&
-        !rolesById.has(action.roleId)
-      ) {
-        addIssue(
-          ctx,
-          ['policies', policy.id, 'actions', actionIndex, 'roleId'],
-          `Policy "${policy.id}" references unknown role "${action.roleId}"`
-        )
-      }
-    })
-
-    if (policy.trigger.kind === 'action-invocation' && !actionsById.has(policy.trigger.actionId)) {
-      addIssue(
-        ctx,
-        ['policies', policy.id, 'trigger', 'actionId'],
-        `Policy "${policy.id}" references unknown trigger action "${policy.trigger.actionId}"`
-      )
-    }
-  })
-
-  function knowledgeTargetExists(kind: string, id: string): boolean {
-    if (kind === 'system') return systemsById.has(id)
-    if (kind === 'resource') return resourcesById.has(id)
-    if (kind === 'knowledge') return knowledgeById.has(id)
-    if (kind === 'stage') return stageIds.has(id)
-    if (kind === 'action') return actionIds.has(id)
-    if (kind === 'role') return rolesById.has(id)
-    if (kind === 'goal') return goalsById.has(id)
-    if (kind === 'customer-segment') return segmentsById.has(id)
-    if (kind === 'offering') return offeringsById.has(id)
-    if (kind === 'ontology') return ontologyIds.has(id)
-    return false
-  }
-
-  // Phase 4: model.knowledge is now Record<id, OrgKnowledgeNode> — iterate Object.values
-  Object.entries(model.knowledge).forEach(([nodeId, node]) => {
-    node.links.forEach((link, linkIndex) => {
-      if (!knowledgeTargetExists(link.target.kind, link.target.id)) {
-        addIssue(
-          ctx,
-          ['knowledge', nodeId, 'links', linkIndex, 'target'],
-          `Knowledge node "${node.id}" references unknown ${link.target.kind} target "${link.target.id}"`
-        )
-      }
-
-      if (!isKnowledgeKindCompatibleWithTarget(node.kind, link.target.kind)) {
-        addIssue(
-          ctx,
-          ['knowledge', nodeId, 'links', linkIndex, 'target', 'kind'],
-          `Knowledge node "${node.id}" kind "${node.kind}" cannot govern ${link.target.kind} targets`
-        )
-      }
-
-      // `governedByKnowledge` is validated one-way on target nodes above. Knowledge
-      // links may be authored first and remain valid as forward references.
-    })
-  })
-
-  Object.values(model.resources).forEach((resource) => {
-    if (!systemsById.has(resource.systemPath)) {
-      addIssue(
-        ctx,
-        ['resources', resource.id, 'systemPath'],
-        `Resource "${resource.id}" references unknown system path "${resource.systemPath}"`
-      )
-    }
-
-    if (resource.ownerRoleId !== undefined && !rolesById.has(resource.ownerRoleId)) {
-      addIssue(
-        ctx,
-        ['resources', resource.id, 'ownerRoleId'],
-        `Resource "${resource.id}" references unknown ownerRoleId "${resource.ownerRoleId}"`
-      )
-    }
-
-    if (resource.kind === 'agent' && resource.actsAsRoleId !== undefined && !rolesById.has(resource.actsAsRoleId)) {
-      addIssue(
-        ctx,
-        ['resources', resource.id, 'actsAsRoleId'],
-        `Agent resource "${resource.id}" references unknown actsAsRoleId "${resource.actsAsRoleId}"`
-      )
-    }
-  })
-
-  function validateResourceOntologyBinding(
-    resourceId: string,
-    bindingKey: 'actions' | 'primaryAction' | 'reads' | 'writes' | 'usesCatalogs' | 'emits',
-    expectedKind: OntologyKind,
-    ids: string[] | string | undefined
-  ): void {
-    const ontologyIds = ids === undefined ? [] : Array.isArray(ids) ? ids : [ids]
-
-    ontologyIds.forEach((ontologyId, ontologyIndex) => {
-      if (ontologyIndexByKind[expectedKind][ontologyId] === undefined) {
-        addIssue(
-          ctx,
-          ['resources', resourceId, 'ontology', bindingKey, ...(Array.isArray(ids) ? [ontologyIndex] : [])],
-          `Resource "${resourceId}" ontology binding "${bindingKey}" references unknown ${expectedKind} ontology ID "${ontologyId}"`
-        )
-      }
-    })
-  }
-
-  Object.values(model.resources).forEach((resource) => {
-    const binding = resource.ontology
-    if (binding === undefined) return
-
-    validateResourceOntologyBinding(resource.id, 'actions', 'action', binding.actions)
-    validateResourceOntologyBinding(resource.id, 'primaryAction', 'action', binding.primaryAction)
-    validateResourceOntologyBinding(resource.id, 'reads', 'object', binding.reads)
-    validateResourceOntologyBinding(resource.id, 'writes', 'object', binding.writes)
-    validateResourceOntologyBinding(resource.id, 'usesCatalogs', 'catalog', binding.usesCatalogs)
-    validateResourceOntologyBinding(resource.id, 'emits', 'event', binding.emits)
-
-    // Tier-1: validate contract ref SHAPE only — no module resolution (browser-safe).
-    // Tier-2 intra-package resolution runs in om:verify (packages/cli/src/knowledge/verify.ts).
-    if (binding.contract !== undefined) {
-      const contractEntries = [
-        ['input', binding.contract.input],
-        ['output', binding.contract.output]
-      ] as const
-      for (const [side, ref] of contractEntries) {
-        if (ref === undefined) continue
-        const result = ContractRefSchema.safeParse(ref)
-        if (!result.success) {
-          addIssue(
-            ctx,
-            ['resources', resource.id, 'ontology', 'contract', side],
-            `Resource "${resource.id}" contract.${side} "${ref}" is not a valid ContractRef (expected "package/subpath#ExportName")`
-          )
-        }
-      }
-    }
-  })
-
-  Object.values(model.roles).forEach((role) => {
-    if (role.heldBy === undefined) return
-
-    asRoleHolderArray(role.heldBy).forEach((holder, holderIndex) => {
-      if (holder.kind !== 'agent') return
-
-      const resource = resourcesById.get(holder.agentId)
-      if (resource === undefined) {
-        addIssue(
-          ctx,
-          ['roles', role.id, 'heldBy', Array.isArray(role.heldBy) ? holderIndex : 'agentId'],
-          `Role "${role.id}" references unknown agent holder resource "${holder.agentId}"`
-        )
-        return
-      }
-
-      if (resource.kind !== 'agent') {
-        addIssue(
-          ctx,
-          ['roles', role.id, 'heldBy', Array.isArray(role.heldBy) ? holderIndex : 'agentId'],
-          `Role "${role.id}" agent holder "${holder.agentId}" must reference an agent resource`
-        )
-      }
-    })
-  })
-
-  // Phase 4: model.knowledge is now Record<id, OrgKnowledgeNode>
-  Object.entries(model.knowledge).forEach(([nodeId, node]) => {
-    node.ownerIds.forEach((roleId, ownerIndex) => {
-      if (!rolesById.has(roleId)) {
-        addIssue(
-          ctx,
-          ['knowledge', nodeId, 'ownerIds', ownerIndex],
-          `Knowledge node "${node.id}" references unknown owner role "${roleId}"`
-        )
-      }
-    })
-  })
-
-  for (const diagnostic of ontologyCompilation.diagnostics) {
-    addIssue(ctx, diagnostic.path, diagnostic.message)
-  }
-})
+declare const OrganizationModelSchema = OrganizationModelSchemaBase.superRefine(refineOrganizationModel)
 
 type OrganizationModel = z.infer<typeof OrganizationModelSchema>
 type OrganizationModelResourceOntologyBinding = z.infer<typeof ResourceOntologyBindingSchema>