@almadar/core 10.31.0 → 10.32.0

package/dist/{pattern-types-VDIr2TkX.d.ts → effect-8eas3tpU.d.ts}

@@ -1,5 +1,749 @@
 import { z } from 'zod';
-import { S as SExpr } from './expression-CB9R3KWk.js';
+import { S as SExpr, c as EventPayload, E as Expression } from './expression-BlFrxmNB.js';
+
+/**
+ * Service Types for Orbital Schema
+ *
+ * Defines external service integrations (REST APIs, WebSockets, MCP servers)
+ * that can be used by orbital units via the `call_service` effect.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Types of external services that can be integrated.
+ */
+declare const SERVICE_TYPES: readonly ["rest", "socket", "mcp"];
+type ServiceType = (typeof SERVICE_TYPES)[number];
+declare const ServiceTypeSchema: z.ZodEnum<["rest", "socket", "mcp"]>;
+/**
+ * Configuration for a REST API service.
+ *
+ * @example
+ * ```typescript
+ * const weatherService: RestServiceDef = {
+ *   name: 'WeatherAPI',
+ *   type: 'rest',
+ *   baseUrl: 'https://api.openweathermap.org/data/2.5',
+ *   headers: {
+ *     'Content-Type': 'application/json',
+ *   },
+ *   auth: {
+ *     type: 'api-key',
+ *     keyName: 'appid',
+ *     location: 'query',
+ *   },
+ * };
+ * ```
+ */
+type RestServiceDef = {
+    /** Unique service name (used in call_service effect) */
+    name: string;
+    /** Service type */
+    type: "rest";
+    /** Optional description */
+    description?: string;
+    /** Base URL for the API */
+    baseUrl: string;
+    /** Default headers to include in all requests */
+    headers?: Record<string, string>;
+    /** Authentication configuration */
+    auth?: RestAuthConfig;
+    /** Timeout in milliseconds (default: 30000) */
+    timeout?: number;
+};
+/**
+ * Authentication configuration for REST services.
+ */
+type RestAuthConfig = {
+    /** Authentication type */
+    type: "api-key" | "bearer" | "basic" | "oauth2";
+    /** For api-key: the query parameter or header name */
+    keyName?: string;
+    /** For api-key: where to place the key */
+    location?: "query" | "header";
+    /** Environment variable name containing the secret (for secure storage) */
+    secretEnv?: string;
+};
+declare const RestAuthConfigSchema: z.ZodObject<{
+    type: z.ZodEnum<["api-key", "bearer", "basic", "oauth2"]>;
+    keyName: z.ZodOptional<z.ZodString>;
+    location: z.ZodOptional<z.ZodEnum<["query", "header"]>>;
+    secretEnv: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "api-key" | "bearer" | "basic" | "oauth2";
+    keyName?: string | undefined;
+    location?: "query" | "header" | undefined;
+    secretEnv?: string | undefined;
+}, {
+    type: "api-key" | "bearer" | "basic" | "oauth2";
+    keyName?: string | undefined;
+    location?: "query" | "header" | undefined;
+    secretEnv?: string | undefined;
+}>;
+declare const RestServiceDefSchema: z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodLiteral<"rest">;
+    description: z.ZodOptional<z.ZodString>;
+    baseUrl: z.ZodString;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    auth: z.ZodOptional<z.ZodObject<{
+        type: z.ZodEnum<["api-key", "bearer", "basic", "oauth2"]>;
+        keyName: z.ZodOptional<z.ZodString>;
+        location: z.ZodOptional<z.ZodEnum<["query", "header"]>>;
+        secretEnv: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        type: "api-key" | "bearer" | "basic" | "oauth2";
+        keyName?: string | undefined;
+        location?: "query" | "header" | undefined;
+        secretEnv?: string | undefined;
+    }, {
+        type: "api-key" | "bearer" | "basic" | "oauth2";
+        keyName?: string | undefined;
+        location?: "query" | "header" | undefined;
+        secretEnv?: string | undefined;
+    }>>;
+    timeout: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    type: "rest";
+    name: string;
+    baseUrl: string;
+    description?: string | undefined;
+    headers?: Record<string, string> | undefined;
+    auth?: {
+        type: "api-key" | "bearer" | "basic" | "oauth2";
+        keyName?: string | undefined;
+        location?: "query" | "header" | undefined;
+        secretEnv?: string | undefined;
+    } | undefined;
+    timeout?: number | undefined;
+}, {
+    type: "rest";
+    name: string;
+    baseUrl: string;
+    description?: string | undefined;
+    headers?: Record<string, string> | undefined;
+    auth?: {
+        type: "api-key" | "bearer" | "basic" | "oauth2";
+        keyName?: string | undefined;
+        location?: "query" | "header" | undefined;
+        secretEnv?: string | undefined;
+    } | undefined;
+    timeout?: number | undefined;
+}>;
+/**
+ * Configuration for a WebSocket service.
+ *
+ * @example
+ * ```typescript
+ * const chatService: SocketServiceDef = {
+ *   name: 'ChatSocket',
+ *   type: 'socket',
+ *   url: 'wss://chat.example.com',
+ *   events: {
+ *     inbound: ['message_received', 'user_joined', 'user_left'],
+ *     outbound: ['send_message', 'join_room', 'leave_room'],
+ *   },
+ * };
+ * ```
+ */
+type SocketServiceDef = {
+    /** Unique service name */
+    name: string;
+    /** Service type */
+    type: "socket";
+    /** Optional description */
+    description?: string;
+    /** WebSocket URL */
+    url: string;
+    /** Event definitions */
+    events: SocketEvents;
+    /** Reconnection configuration */
+    reconnect?: {
+        /** Enable automatic reconnection */
+        enabled: boolean;
+        /** Maximum reconnection attempts */
+        maxAttempts?: number;
+        /** Delay between attempts in ms */
+        delayMs?: number;
+    };
+};
+/**
+ * Socket event definitions.
+ */
+type SocketEvents = {
+    /** Events received from server (maps to orbital events) */
+    inbound: string[];
+    /** Events sent to server (triggered by effects) */
+    outbound: string[];
+};
+declare const SocketEventsSchema: z.ZodObject<{
+    inbound: z.ZodArray<z.ZodString, "many">;
+    outbound: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    inbound: string[];
+    outbound: string[];
+}, {
+    inbound: string[];
+    outbound: string[];
+}>;
+declare const SocketServiceDefSchema: z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodLiteral<"socket">;
+    description: z.ZodOptional<z.ZodString>;
+    url: z.ZodString;
+    events: z.ZodObject<{
+        inbound: z.ZodArray<z.ZodString, "many">;
+        outbound: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        inbound: string[];
+        outbound: string[];
+    }, {
+        inbound: string[];
+        outbound: string[];
+    }>;
+    reconnect: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        maxAttempts: z.ZodOptional<z.ZodNumber>;
+        delayMs: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        enabled: boolean;
+        maxAttempts?: number | undefined;
+        delayMs?: number | undefined;
+    }, {
+        enabled: boolean;
+        maxAttempts?: number | undefined;
+        delayMs?: number | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    type: "socket";
+    url: string;
+    name: string;
+    events: {
+        inbound: string[];
+        outbound: string[];
+    };
+    description?: string | undefined;
+    reconnect?: {
+        enabled: boolean;
+        maxAttempts?: number | undefined;
+        delayMs?: number | undefined;
+    } | undefined;
+}, {
+    type: "socket";
+    url: string;
+    name: string;
+    events: {
+        inbound: string[];
+        outbound: string[];
+    };
+    description?: string | undefined;
+    reconnect?: {
+        enabled: boolean;
+        maxAttempts?: number | undefined;
+        delayMs?: number | undefined;
+    } | undefined;
+}>;
+/**
+ * Configuration for an MCP (Model Context Protocol) server.
+ *
+ * @example
+ * ```typescript
+ * const mcpService: McpServiceDef = {
+ *   name: 'DatabaseMCP',
+ *   type: 'mcp',
+ *   serverPath: './mcp-servers/database',
+ *   capabilities: ['query', 'insert', 'update'],
+ * };
+ * ```
+ */
+type McpServiceDef = {
+    /** Unique service name */
+    name: string;
+    /** Service type */
+    type: "mcp";
+    /** Optional description */
+    description?: string;
+    /** Path to MCP server executable or module */
+    serverPath: string;
+    /** List of capabilities/tools exposed by the MCP server */
+    capabilities: string[];
+    /** Environment variables to pass to the MCP server */
+    env?: Record<string, string>;
+};
+declare const McpServiceDefSchema: z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodLiteral<"mcp">;
+    description: z.ZodOptional<z.ZodString>;
+    serverPath: z.ZodString;
+    capabilities: z.ZodArray<z.ZodString, "many">;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    type: "mcp";
+    name: string;
+    serverPath: string;
+    capabilities: string[];
+    description?: string | undefined;
+    env?: Record<string, string> | undefined;
+}, {
+    type: "mcp";
+    name: string;
+    serverPath: string;
+    capabilities: string[];
+    description?: string | undefined;
+    env?: Record<string, string> | undefined;
+}>;
+/**
+ * Union type for all service definitions.
+ */
+type ServiceDefinition = RestServiceDef | SocketServiceDef | McpServiceDef;
+declare const ServiceDefinitionSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodLiteral<"rest">;
+    description: z.ZodOptional<z.ZodString>;
+    baseUrl: z.ZodString;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    auth: z.ZodOptional<z.ZodObject<{
+        type: z.ZodEnum<["api-key", "bearer", "basic", "oauth2"]>;
+        keyName: z.ZodOptional<z.ZodString>;
+        location: z.ZodOptional<z.ZodEnum<["query", "header"]>>;
+        secretEnv: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        type: "api-key" | "bearer" | "basic" | "oauth2";
+        keyName?: string | undefined;
+        location?: "query" | "header" | undefined;
+        secretEnv?: string | undefined;
+    }, {
+        type: "api-key" | "bearer" | "basic" | "oauth2";
+        keyName?: string | undefined;
+        location?: "query" | "header" | undefined;
+        secretEnv?: string | undefined;
+    }>>;
+    timeout: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    type: "rest";
+    name: string;
+    baseUrl: string;
+    description?: string | undefined;
+    headers?: Record<string, string> | undefined;
+    auth?: {
+        type: "api-key" | "bearer" | "basic" | "oauth2";
+        keyName?: string | undefined;
+        location?: "query" | "header" | undefined;
+        secretEnv?: string | undefined;
+    } | undefined;
+    timeout?: number | undefined;
+}, {
+    type: "rest";
+    name: string;
+    baseUrl: string;
+    description?: string | undefined;
+    headers?: Record<string, string> | undefined;
+    auth?: {
+        type: "api-key" | "bearer" | "basic" | "oauth2";
+        keyName?: string | undefined;
+        location?: "query" | "header" | undefined;
+        secretEnv?: string | undefined;
+    } | undefined;
+    timeout?: number | undefined;
+}>, z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodLiteral<"socket">;
+    description: z.ZodOptional<z.ZodString>;
+    url: z.ZodString;
+    events: z.ZodObject<{
+        inbound: z.ZodArray<z.ZodString, "many">;
+        outbound: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        inbound: string[];
+        outbound: string[];
+    }, {
+        inbound: string[];
+        outbound: string[];
+    }>;
+    reconnect: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        maxAttempts: z.ZodOptional<z.ZodNumber>;
+        delayMs: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        enabled: boolean;
+        maxAttempts?: number | undefined;
+        delayMs?: number | undefined;
+    }, {
+        enabled: boolean;
+        maxAttempts?: number | undefined;
+        delayMs?: number | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    type: "socket";
+    url: string;
+    name: string;
+    events: {
+        inbound: string[];
+        outbound: string[];
+    };
+    description?: string | undefined;
+    reconnect?: {
+        enabled: boolean;
+        maxAttempts?: number | undefined;
+        delayMs?: number | undefined;
+    } | undefined;
+}, {
+    type: "socket";
+    url: string;
+    name: string;
+    events: {
+        inbound: string[];
+        outbound: string[];
+    };
+    description?: string | undefined;
+    reconnect?: {
+        enabled: boolean;
+        maxAttempts?: number | undefined;
+        delayMs?: number | undefined;
+    } | undefined;
+}>, z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodLiteral<"mcp">;
+    description: z.ZodOptional<z.ZodString>;
+    serverPath: z.ZodString;
+    capabilities: z.ZodArray<z.ZodString, "many">;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    type: "mcp";
+    name: string;
+    serverPath: string;
+    capabilities: string[];
+    description?: string | undefined;
+    env?: Record<string, string> | undefined;
+}, {
+    type: "mcp";
+    name: string;
+    serverPath: string;
+    capabilities: string[];
+    description?: string | undefined;
+    env?: Record<string, string> | undefined;
+}>]>;
+/**
+ * ServiceRef - Service can be inline definition, reference object with overrides,
+ * or bare string reference to an imported service.
+ *
+ * Reference format: "Alias.services.ServiceName"
+ */
+type ServiceRef = ServiceDefinition | ServiceRefObject | string;
+/**
+ * Phase F: Service reference object with override fields.
+ *
+ * Mirrors the Rust `ServiceRefObject` at
+ * `orbital-rust/crates/orbital-core/src/schema/types.rs:353-375`. A caller
+ * imports a service via `uses[]`, references it by `ref`, and supplies
+ * any subset of these fields to override the imported service's defaults
+ * during inlining.
+ *
+ * @example
+ * ```typescript
+ * const ref: ServiceRefObject = {
+ *   ref: "Weather.services.openweather",
+ *   baseUrl: "https://staging.weather.example.com",
+ *   headers: { "X-Tenant": "acme" },
+ * };
+ * ```
+ */
+type ServiceRefObject = {
+    /** Reference to imported service: "Alias.services.ServiceName" */
+    ref: string;
+    /** Override the service description */
+    description?: string;
+    /** Override the REST baseUrl */
+    baseUrl?: string;
+    /** Override or merge default headers (caller wins on key collision) */
+    headers?: Record<string, string>;
+    /** Override the WebSocket url */
+    url?: string;
+    /** Override the MCP server path */
+    serverPath?: string;
+};
+/**
+ * Checks if a service reference is a bare string reference.
+ *
+ * Type guard to determine if a service reference is a string reference
+ * (format: "Alias.services.ServiceName") rather than an inline service
+ * definition or a reference object.
+ *
+ * @param {ServiceRef} service - Service reference to check
+ * @returns {boolean} True if service is a string reference, false otherwise
+ *
+ * @example
+ * isServiceReference("Weather.services.openweather"); // returns true
+ * isServiceReference({ name: "weather", type: "rest" }); // returns false
+ * isServiceReference({ ref: "Weather.services.openweather" }); // returns false
+ */
+declare function isServiceReference(service: ServiceRef): service is string;
+/**
+ * Phase F: Type guard for `ServiceRefObject` (the override-carrying form).
+ *
+ * @param {ServiceRef} service - Service reference to check
+ * @returns {boolean} True if service is a ServiceRefObject
+ */
+declare function isServiceReferenceObject(service: ServiceRef): service is ServiceRefObject;
+/**
+ * Validate service reference format: "Alias.services.ServiceName"
+ */
+declare const ServiceRefStringSchema: z.ZodString;
+declare const ServiceRefObjectSchema: z.ZodObject<{
+    ref: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    baseUrl: z.ZodOptional<z.ZodString>;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    url: z.ZodOptional<z.ZodString>;
+    serverPath: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    ref: string;
+    url?: string | undefined;
+    description?: string | undefined;
+    baseUrl?: string | undefined;
+    headers?: Record<string, string> | undefined;
+    serverPath?: string | undefined;
+}, {
+    ref: string;
+    url?: string | undefined;
+    description?: string | undefined;
+    baseUrl?: string | undefined;
+    headers?: Record<string, string> | undefined;
+    serverPath?: string | undefined;
+}>;
+declare const ServiceRefSchema: z.ZodUnion<[z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodLiteral<"rest">;
+    description: z.ZodOptional<z.ZodString>;
+    baseUrl: z.ZodString;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    auth: z.ZodOptional<z.ZodObject<{
+        type: z.ZodEnum<["api-key", "bearer", "basic", "oauth2"]>;
+        keyName: z.ZodOptional<z.ZodString>;
+        location: z.ZodOptional<z.ZodEnum<["query", "header"]>>;
+        secretEnv: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        type: "api-key" | "bearer" | "basic" | "oauth2";
+        keyName?: string | undefined;
+        location?: "query" | "header" | undefined;
+        secretEnv?: string | undefined;
+    }, {
+        type: "api-key" | "bearer" | "basic" | "oauth2";
+        keyName?: string | undefined;
+        location?: "query" | "header" | undefined;
+        secretEnv?: string | undefined;
+    }>>;
+    timeout: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    type: "rest";
+    name: string;
+    baseUrl: string;
+    description?: string | undefined;
+    headers?: Record<string, string> | undefined;
+    auth?: {
+        type: "api-key" | "bearer" | "basic" | "oauth2";
+        keyName?: string | undefined;
+        location?: "query" | "header" | undefined;
+        secretEnv?: string | undefined;
+    } | undefined;
+    timeout?: number | undefined;
+}, {
+    type: "rest";
+    name: string;
+    baseUrl: string;
+    description?: string | undefined;
+    headers?: Record<string, string> | undefined;
+    auth?: {
+        type: "api-key" | "bearer" | "basic" | "oauth2";
+        keyName?: string | undefined;
+        location?: "query" | "header" | undefined;
+        secretEnv?: string | undefined;
+    } | undefined;
+    timeout?: number | undefined;
+}>, z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodLiteral<"socket">;
+    description: z.ZodOptional<z.ZodString>;
+    url: z.ZodString;
+    events: z.ZodObject<{
+        inbound: z.ZodArray<z.ZodString, "many">;
+        outbound: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        inbound: string[];
+        outbound: string[];
+    }, {
+        inbound: string[];
+        outbound: string[];
+    }>;
+    reconnect: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        maxAttempts: z.ZodOptional<z.ZodNumber>;
+        delayMs: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        enabled: boolean;
+        maxAttempts?: number | undefined;
+        delayMs?: number | undefined;
+    }, {
+        enabled: boolean;
+        maxAttempts?: number | undefined;
+        delayMs?: number | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    type: "socket";
+    url: string;
+    name: string;
+    events: {
+        inbound: string[];
+        outbound: string[];
+    };
+    description?: string | undefined;
+    reconnect?: {
+        enabled: boolean;
+        maxAttempts?: number | undefined;
+        delayMs?: number | undefined;
+    } | undefined;
+}, {
+    type: "socket";
+    url: string;
+    name: string;
+    events: {
+        inbound: string[];
+        outbound: string[];
+    };
+    description?: string | undefined;
+    reconnect?: {
+        enabled: boolean;
+        maxAttempts?: number | undefined;
+        delayMs?: number | undefined;
+    } | undefined;
+}>, z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodLiteral<"mcp">;
+    description: z.ZodOptional<z.ZodString>;
+    serverPath: z.ZodString;
+    capabilities: z.ZodArray<z.ZodString, "many">;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    type: "mcp";
+    name: string;
+    serverPath: string;
+    capabilities: string[];
+    description?: string | undefined;
+    env?: Record<string, string> | undefined;
+}, {
+    type: "mcp";
+    name: string;
+    serverPath: string;
+    capabilities: string[];
+    description?: string | undefined;
+    env?: Record<string, string> | undefined;
+}>]>, z.ZodObject<{
+    ref: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    baseUrl: z.ZodOptional<z.ZodString>;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    url: z.ZodOptional<z.ZodString>;
+    serverPath: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    ref: string;
+    url?: string | undefined;
+    description?: string | undefined;
+    baseUrl?: string | undefined;
+    headers?: Record<string, string> | undefined;
+    serverPath?: string | undefined;
+}, {
+    ref: string;
+    url?: string | undefined;
+    description?: string | undefined;
+    baseUrl?: string | undefined;
+    headers?: Record<string, string> | undefined;
+    serverPath?: string | undefined;
+}>, z.ZodString]>;
+/**
+ * Parses a service reference into its components.
+ *
+ * Extracts the alias and service name from a service reference string
+ * in format "Alias.services.ServiceName". Returns null if not a valid reference.
+ *
+ * @param {string} ref - Service reference string
+ * @returns {{ alias: string; serviceName: string } | null} Parsed components or null
+ *
+ * @example
+ * parseServiceRef("Weather.services.openweather"); // returns { alias: "Weather", serviceName: "openweather" }
+ * parseServiceRef("invalid"); // returns null
+ */
+declare function parseServiceRef(ref: string): {
+    alias: string;
+    serviceName: string;
+} | null;
+/**
+ * Checks if a service definition is a REST service.
+ *
+ * Type guard to determine if a service definition represents a REST API service.
+ * Used for service type discrimination and validation.
+ *
+ * @param {ServiceDefinition} service - Service definition to check
+ * @returns {boolean} True if service is a REST service, false otherwise
+ *
+ * @example
+ * isRestService({ name: "weather", type: "rest", baseUrl: "..." }); // returns true
+ * isRestService({ name: "chat", type: "socket" }); // returns false
+ */
+declare function isRestService(service: ServiceDefinition): service is RestServiceDef;
+/**
+ * Checks if a service definition is a Socket service.
+ *
+ * Type guard to determine if a service definition represents a WebSocket service.
+ * Used for service type discrimination and validation.
+ *
+ * @param {ServiceDefinition} service - Service definition to check
+ * @returns {boolean} True if service is a Socket service, false otherwise
+ *
+ * @example
+ * isSocketService({ name: "chat", type: "socket", url: "wss://..." }); // returns true
+ * isSocketService({ name: "weather", type: "rest" }); // returns false
+ */
+declare function isSocketService(service: ServiceDefinition): service is SocketServiceDef;
+/**
+ * Checks if a service definition is an MCP service.
+ *
+ * Type guard to determine if a service definition represents an MCP
+ * (Multiplayer Control Protocol) service. Used for service type discrimination.
+ *
+ * @param {ServiceDefinition} service - Service definition to check
+ * @returns {boolean} True if service is an MCP service, false otherwise
+ *
+ * @example
+ * isMcpService({ name: "game", type: "mcp", serverUrl: "..." }); // returns true
+ * isMcpService({ name: "chat", type: "socket" }); // returns false
+ */
+declare function isMcpService(service: ServiceDefinition): service is McpServiceDef;
+/**
+ * Get all service names from a list of services.
+ */
+declare function getServiceNames(services: ServiceDefinition[]): string[];
+/**
+ * Find a service by name.
+ */
+declare function findService(services: ServiceDefinition[], name: string): ServiceDefinition | undefined;
+/**
+ * Check if a service name exists (case-insensitive).
+ */
+declare function hasService(services: ServiceDefinition[], name: string): boolean;
+/**
+ * Allowed leaf value for `ServiceParams`. Mirrors `EventPayloadValue`'s
+ * recursive-array shape so integration call signatures can express the
+ * nested structures real services need (port mappings, volume mounts,
+ * pagination cursors), and so a value satisfying `EventPayloadValue`
+ * also satisfies `ServiceParamsValue` without a cast — the same data
+ * flows through `call-service` and `emit` without boundary widening.
+ */
+type ServiceParamsValue = string | number | boolean | Date | null | undefined | ServiceParams | readonly ServiceParamsValue[];
+/** Parameters passed to call-service effects. Recursive for nested request shapes. */
+type ServiceParams = {
+    [key: string]: ServiceParamsValue;
+};
 
 /**
  * Identity model (Almadar Rabit V4, Phase 1 — types only).
@@ -1563,7 +2307,7 @@ type EntityData = Record<string, EntityRow[]>;
  *
  * DO NOT EDIT MANUALLY — regenerated by almadar-pattern-sync `patterns` command.
  *
- * Generated: 2026-07-21T09:54:57.817Z
+ * Generated: 2026-07-23T14:32:35.967Z
  * Pattern count: 263
  */
 
@@ -2596,7 +3340,7 @@ interface PatternPropsMap {
         type: 'drawer';
         isOpen?: boolean | string | SExpr;
         onClose?: ((...args: unknown[]) => unknown) | string | SExpr;
-        title?: string | SExpr;
+        title?: unknown | string | SExpr;
         children?: unknown | string | SExpr;
         footer?: unknown | string | SExpr;
         position?: string | SExpr;
@@ -2803,6 +3547,8 @@ interface PatternPropsMap {
         query?: string | SExpr;
         isLoading?: boolean | string | SExpr;
         look?: string | SExpr;
+        event?: string | SExpr;
+        clearEvent?: string | SExpr;
     };
     'filter-pill': {
         type: 'filter-pill';
@@ -4959,4 +5705,711 @@ declare const PATTERN_TYPES: PatternType[];
  */
 declare function isValidPatternType(type: string): type is PatternType;
 
-export { type FieldFormat as $, type AnyPatternConfig as A, type AssetUrl as B, CAMERA_MODES as C, type Camera as D, type EntityField as E, type FieldValue as F, type CameraMode as G, CameraModeSchema as H, CameraSchema as I, type JsonValue as J, ENTITY_ROLES as K, type EntityData as L, type EntityFieldInput as M, EntityFieldSchema as N, type OrbitalId as O, type PageId as P, EntityIdSchema as Q, type RelationConfig as R, EntityPersistenceSchema as S, type TraitId as T, type EntityRole as U, EntityRoleSchema as V, EntitySchema as W, type EntityWith as X, type EnumEntityField as Y, EventIdSchema as Z, type Field as _, type EntityPersistence as a, getDefaultAnimationsForRole as a$, FieldFormatSchema as a0, FieldSchema as a1, type FieldType as a2, FieldTypeSchema as a3, type IdForKind as a4, type IdKind as a5, type IdentityLedger as a6, IdentityLedgerSchema as a7, type JsonObject as a8, type LedgerEntry as a9, type SpriteDirection as aA, SpriteDirectionSchema as aB, type SpriteSheetAtlas as aC, type SpriteSheetAtlasInput as aD, SpriteSheetAtlasSchema as aE, type SubTexture as aF, SubTextureSchema as aG, type TextureAtlas as aH, TextureAtlasSchema as aI, type ThemeId as aJ, ThemeIdSchema as aK, type Tilesheet as aL, TilesheetSchema as aM, TraitIdSchema as aN, VISUAL_STYLES as aO, type VisualStyle as aP, VisualStyleSchema as aQ, asEntityId as aR, asEventId as aS, asOrbitalId as aT, asPageId as aU, asPaletteEntryId as aV, asServiceId as aW, asThemeId as aX, asTraitId as aY, createAssetKey as aZ, deriveCollection as a_, LedgerEntrySchema as aa, type LedgerKind as ab, LedgerKindSchema as ac, type OrbitalEntity as ad, type OrbitalEntityInput as ae, OrbitalEntitySchema as af, OrbitalIdSchema as ag, PATTERN_TYPES as ah, PageIdSchema as ai, type PaletteEntryId as aj, PaletteEntryIdSchema as ak, type PatternConfig as al, type PatternProps as am, type PatternPropsMap as an, type PatternType as ao, RelationConfigSchema as ap, type RelationEntityField as aq, SPRITE_DIRECTIONS as ar, type ScalarEntityField as as, type ScenePos as at, ScenePosSchema as au, type SemanticAssetRef as av, type SemanticAssetRefInput as aw, SemanticAssetRefSchema as ax, type ServiceId as ay, ServiceIdSchema as az, type EntityRow as b, idKindOf as b0, idPrefix as b1, isEntityId as b2, isEventId as b3, isFieldValue as b4, isJsonArray as b5, isJsonObject as b6, isJsonPrimitive as b7, isOrbitalId as b8, isPageId as b9, isPaletteEntryId as ba, isRuntimeEntity as bb, isServiceId as bc, isThemeId as bd, isTraitId as be, isValidPatternType as bf, ledgerCurName as bg, ledgerRename as bh, ledgerResolveName as bi, mintId as bj, parseAssetKey as bk, persistenceModeAllowsOverrides as bl, validateAssetAnimations as bm, type EventId as c, type EntityId as d, type Entity as e, type ToolArgs as f, ANIMATION_NAMES as g, ASSET_ASPECTS as h, ASSET_DIMENSIONS as i, type AnimationDef as j, type AnimationDefInput as k, AnimationDefSchema as l, type AnimationName as m, AnimationNameSchema as n, type ArrayEntityField as o, type Asset as p, type AssetAspect as q, AssetAspectSchema as r, type AssetCatalog as s, type AssetCatalogEntry as t, type AssetCatalogEntryInput as u, AssetCatalogEntrySchema as v, AssetCatalogSchema as w, type AssetDimension as x, AssetDimensionSchema as y, AssetSchema as z };
+/**
+ * Effect Types (Self-Contained)
+ *
+ * Defines effect types for trait transitions and ticks.
+ * Effects are S-expressions (arrays) that describe actions to perform.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Known UI slots where content can be rendered
+ */
+declare const UI_SLOTS: readonly ["main", "sidebar", "modal", "drawer", "overlay", "center", "toast", "floating", "system", "content", "screen", "hud", "hud-top", "hud-bottom", "hud.health", "hud.score", "hud.inventory", "hud.stamina", "overlay.inventory", "overlay.dialogue", "overlay.menu", "overlay.pause"];
+type UISlot = (typeof UI_SLOTS)[number];
+declare const UISlotSchema: z.ZodEnum<["main", "sidebar", "modal", "drawer", "overlay", "center", "toast", "floating", "system", "content", "screen", "hud", "hud-top", "hud-bottom", "hud.health", "hud.score", "hud.inventory", "hud.stamina", "overlay.inventory", "overlay.dialogue", "overlay.menu", "overlay.pause"]>;
+
+/**
+ * Configuration extracted from call-service effects
+ */
+type CallServiceConfig = {
+    service: string;
+    action: string;
+    endpoint?: string;
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    params?: ServiceParams;
+    onSuccess?: string;
+    onError?: string;
+};
+/**
+ * A binding reference to a render tree stored elsewhere — a trait `config`
+ * knob or a payload field — e.g. `"@config.bodyContent"`. Resolved to a pattern
+ * node at render time. This is how an atom renders a tree that contains data
+ * bindings (`entity: "@payload.data"`, `fields: "@config.fields"`): the tree is
+ * a permissive `TraitConfigValue` stored in `config` (a binding string is not a
+ * valid `AnyPatternConfig` prop value), and the render-ui effect points at it.
+ * Worked example: `std-browse`'s loaded transition is `['render-ui', 'main',
+ * '@config.bodyContent']`. The Rust validator accepts this form; this variant
+ * lets the TS effect type express it.
+ */
+type RenderBinding = `@${string}`;
+/**
+ * Render UI effect - displays a pattern in a UI slot.
+ * @example ['render-ui', 'main', { patternType: 'entity-table', columns: ['name'] }]
+ * @example ['render-ui', 'main', '@config.bodyContent']  // a {@link RenderBinding} target
+ */
+type RenderUIEffect = ['render-ui', UISlot, AnyPatternConfig] | ['render-ui', UISlot, AnyPatternConfig, ResolvedPatternProps] | ['render-ui', UISlot, RenderBinding] | ['render-ui', UISlot, null];
+/**
+ * Lambda expression for per-item rendering in data-grid/data-list.
+ * The compiler generates: {(paramName: Record<string, unknown>) => (<>JSX</>)}
+ * where @{paramName}.field bindings reference the current iteration item.
+ *
+ * @example ["fn", "item", { "type": "stack", "children": [{ "type": "typography", "content": "@item.title" }] }]
+ */
+type RenderItemLambda = ['fn', string, AnyPatternConfig];
+/**
+ * Dynamic-collection children entry: renders one child per item of a collection
+ * expression, authored inline in a `children:` position and kept verbatim as IR
+ * (no new node kind). The collection expression is an {@link SExpr} evaluated at
+ * render time; the {@link RenderItemLambda} body is instantiated per item with
+ * the lambda param bound as an `@item`-scope binding. Both execution paths lower
+ * onto the one lambda + `@item` + splice machinery.
+ *
+ * @example ["array/map", "@entity.tasks", ["fn", "item", { "type": "typography", "content": "@item.title" }]]
+ */
+type RenderChildrenMap = ['array/map', SExpr, RenderItemLambda];
+/**
+ * Navigate effect - navigates to an internal page path or an external URL.
+ * @example ['navigate', '/tasks'] or ['navigate', '/tasks/:id', { id: '123' }]
+ * @example ['navigate', 'https://example.com']
+ */
+type NavigateEffect = ['navigate', string | SExpr] | ['navigate', string | SExpr, Record<string, string>];
+/**
+ * Emit effect - emits an event, optionally with payload.
+ * @example ['emit', 'SAVE'] or ['emit', 'PLAYER_DIED', { playerId: '@entity.id' }]
+ * @example ['emit', 'FILTER_CHANGED', '@entity.filters']
+ */
+type EmitEffect = ['emit', string] | ['emit', string, EventPayload | string];
+/**
+ * `emit:` config block attached to async / reactive data operators.
+ *
+ * Each key names an event the runtime should fire on the bus when the
+ * effect reaches the corresponding lifecycle point. The set of keys an
+ * operator actually supports is enforced by the compiler validator:
+ *
+ * | Operator         | Supported keys            |
+ * |------------------|---------------------------|
+ * | `fetch`          | `success`, `failure`      |
+ * | `persist`        | `success`, `failure`      |
+ * | `call-service`   | `success`, `failure`      |
+ * | `set`            | `success`                 |
+ * | `ref`            | `on_change`, `failure`    |
+ * | `os/watch-*`     | `on_message`, `failure`   |
+ *
+ * Payload convention:
+ * - `success` / `on_change` → the effect's result (fetched entity, new value)
+ * - `failure`               → `{ error: string, code?: string }`
+ * - `on_message`            → the incoming message (os/watch-* streams)
+ *
+ * See `docs/Almadar_Std_Gaps.md` §3.1 for the close-the-circuit design.
+ */
+interface EmitConfig {
+    /** Fires after a one-shot async effect resolves successfully. */
+    success?: string;
+    /** Fires when the effect throws; payload is `{ error: string }`. */
+    failure?: string;
+    /** Reactive-subscription event (per update for `ref`). */
+    on_change?: string;
+    /** Per-event fire for `os/watch-*` streams. */
+    on_message?: string;
+}
+/**
+ * Set effect - sets a binding to a value.
+ *
+ * Two forms are supported to match the runtime's `set` handler signature
+ * `(targetId, field, value)`:
+ *
+ * - 3-element binding form (legacy / std behaviors): ['set', '@entity.field', value]
+ * - 4-element target form (canonical runtime): ['set', entityId, fieldName, value]
+ *
+ * The 4-element form is what `OrbitalServerRuntime`'s set handler
+ * dispatches directly (`update(entityType, targetId, { field: value })`).
+ * Prefer the 4-element form when authoring schemas in TypeScript that
+ * load directly into the runtime.
+ *
+ * @example ['set', '@entity.health', 100]                       // 3-element
+ * @example ['set', '@entity.id', 'health', 100]                 // 4-element
+ * @example ['set', '@entity.id', 'count', ['+', '@entity.count', 1]]
+ */
+type SetEffect = ['set', string, unknown] | ['set', string, string, unknown];
+/**
+ * Trailing config object on persist effects. When present, it carries the
+ * `emit` map specifying which events to fire on persist success/failure.
+ * Mirrors what the runtime's `EffectExecutor` reads at the 5th tuple
+ * position. See `(persist create Entity @payload.data { emit: { success:
+ * "Saved", failure: "SaveFailed" } })` in `.lolo` source.
+ */
+type PersistEmitConfig = {
+    emit?: {
+        success?: string;
+        failure?: string;
+    };
+};
+/**
+ * Persist effect data argument: either an entity row literal (field map)
+ * or a binding string referencing a row in scope (e.g. `@payload.data`,
+ * `@entity`). At runtime, binding strings resolve to `EntityRow` values
+ * before the persist op runs.
+ */
+type PersistData = EntityRow | string;
+/**
+ * Persist effect - creates, updates, deletes, or clears entities.
+ *
+ * Each operation accepts an optional trailing `PersistEmitConfig` so the
+ * runtime can fire success / failure events when the operation completes.
+ *
+ * @example ['persist', 'create', 'Task', { title: '@payload.title' }]
+ * @example ['persist', 'update', '@entity.entityType', '@payload.data']
+ * @example ['persist', 'create', 'Task', '@payload.data', { emit: { success: 'TaskCreated' } }]
+ */
+type PersistEffect = ['persist', 'create', string, PersistData] | ['persist', 'create', string, PersistData, PersistEmitConfig] | ['persist', 'update', string, PersistData] | ['persist', 'update', string, PersistData, PersistEmitConfig] | ['persist', 'delete', string] | ['persist', 'delete', string, PersistData] | ['persist', 'delete', string, PersistData, PersistEmitConfig] | ['persist', 'clear', string] | ['persist', 'clear', string, PersistData] | ['persist', 'clear', string, PersistData, PersistEmitConfig];
+/**
+ * Call service effect - invokes an external service.
+ *
+ * Two shapes are accepted:
+ *
+ * 1. Flat form (what the runtime reads and every .orb file uses):
+ *    `['call-service', serviceName, action, params?]` — args[0]=service,
+ *    args[1]=action, args[2]=params. This is the canonical form; the
+ *    runtime's EffectExecutor decodes exactly these positions.
+ *
+ * 2. Legacy config-object form (kept for the `callService()` helper):
+ *    `['call-service', serviceName, CallServiceConfig]` — retained so
+ *    older call sites using the builder helper continue to typecheck.
+ *
+ * @example ['call-service', 'llm', 'generate', { userPrompt: '@entity.inputText' }]
+ * @example ['call-service', 'llm', 'generate', { userPrompt: '...' }, { emit: { success: 'OK', failure: 'ERR' } }]
+ * @example ['call-service', 'WeatherAPI', { service: 'weather', action: 'get', onSuccess: 'OK' }]
+ */
+type CallServiceEffect = ['call-service', string, string] | ['call-service', string, string, ServiceParams] | ['call-service', string, string, ServiceParams, PersistEmitConfig] | ['call-service', string, CallServiceConfig];
+/**
+ * Spawn effect - creates a new entity instance (games).
+ * @example ['spawn', 'Bullet', { x: '@entity.x', y: '@entity.y' }]
+ */
+type SpawnEffect = ['spawn', string] | ['spawn', string, EntityRow];
+/**
+ * Despawn effect - removes an entity instance (games).
+ * @example ['despawn', '@entity.id']
+ */
+type DespawnEffect = ['despawn', string];
+/**
+ * Do effect - executes multiple effects in sequence.
+ * Uses SExpr to allow deeply nested conditionals.
+ * @example ['do', ['set', '@entity.x', 0], ['set', '@entity.y', 0]]
+ */
+type DoEffect = ['do', ...SExpr[]];
+/**
+ * Notify effect - sends a notification.
+ * @example ['notify', 'in_app', 'Task created successfully']
+ * @example ['notify', 'in_app', ['str/concat', 'Item: ', '@entity.name']]
+ */
+type NotifyEffect = ['notify', string, string | SExpr] | ['notify', string, string | SExpr, string];
+/**
+ * Options accepted by `fetch` / `ref` / `deref` effects. Mirrors what
+ * `OrbitalServerRuntime`'s fetch handler reads at runtime: `id`, `filter`,
+ * `limit`, `offset`, `include`, plus the trailing `emit:` map for
+ * success/failure event names.
+ */
+type FetchOptions = {
+    /** Fetch a single entity by ID */
+    id?: string;
+    /** Filter expression (S-expression) */
+    filter?: SExpr;
+    /** Maximum number of entities to return */
+    limit?: number;
+    /** Number of entities to skip */
+    offset?: number;
+    /** Relations to populate (entity field names) */
+    include?: string[];
+    /** Lifecycle events to emit on resolve / reject */
+    emit?: {
+        success?: string;
+        failure?: string;
+    };
+};
+/**
+ * Fetch effect - retrieves entity data (server-side).
+ * @example ['fetch', 'User'] or ['fetch', 'User', { id: '@payload.userId' }]
+ */
+type FetchEffect = ['fetch', string] | ['fetch', string, FetchOptions];
+/**
+ * Result returned by a fetch / ref / deref handler.
+ *
+ * `rows` carries the entity (or entities) that survived `filter` AND
+ * pagination (`offset`/`limit`). `total` is the count of rows that
+ * matched the filter BEFORE pagination, so paginating consumers can
+ * compute `totalPages = ceil(total / pageSize)` without a second
+ * round-trip. Single-entity fetches by id return `total: 1` (or `0`
+ * if not found, in which case the handler returns `null` instead).
+ */
+interface FetchResult {
+    rows: EntityRow | EntityRow[];
+    total: number;
+}
+/**
+ * If effect - conditional effect execution.
+ * Uses SExpr to allow deeply nested conditionals.
+ * @example ['if', ['>', '@entity.health', 0], ['emit', 'ALIVE'], ['emit', 'DEAD']]
+ */
+type IfEffect = ['if', Expression, SExpr] | ['if', Expression, SExpr, SExpr];
+/**
+ * When effect - conditional effect similar to if but without else.
+ * Uses SExpr to allow deeply nested conditionals.
+ * @example ['when', ['>', '@entity.health', 0], ['emit', 'ALIVE']]
+ */
+type WhenEffect = ['when', Expression, SExpr];
+/**
+ * Let effect - creates local bindings for effects.
+ * Uses SExpr to allow deeply nested conditionals.
+ * @example ['let', ['temp', ['get', '@payload.value']], ['set', '@entity.value', 'temp']]
+ */
+type LetEffect = ['let', [string, unknown][], ...SExpr[]];
+/**
+ * Log effect - logs a message for debugging.
+ * @example ['log', 'User created:', '@entity.name']
+ */
+type LogEffect = ['log', ...unknown[]];
+/**
+ * Wait effect - delays execution.
+ * @example ['wait', 1000] - wait 1 second
+ */
+type WaitEffect = ['wait', number];
+/**
+ * Ref effect - creates a reactive entity subscription.
+ * Returns a reactive reference that auto-updates when the entity changes.
+ * @example ['ref', '@entity.health'] - reactive subscription to health
+ * @example ['ref', 'User', { id: '@payload.userId' }] - reactive ref to specific user
+ */
+type RefEffect = ['ref', string] | ['ref', string, FetchOptions];
+/**
+ * Deref effect - snapshot read of an entity value.
+ * Returns the current value without subscribing to changes.
+ * @example ['deref', '@entity.health'] - read current health value
+ * @example ['deref', 'User', { id: '@payload.userId' }] - read specific user snapshot
+ */
+type DerefEffect = ['deref', string] | ['deref', string, FetchOptions];
+/**
+ * Swap! effect - atomic compare-and-swap on an entity field.
+ * Only updates if the current value matches the expected value.
+ * @example ['swap!', '@entity.health', ['fn', ['old'], ['-', 'old', '@payload.damage']]]
+ * @example ['swap!', '@entity.counter', ['+', '@entity.counter', 1]]
+ */
+type SwapEffect = ['swap!', string, SExpr];
+/**
+ * Options accepted by `watch` effects. Mirrors what the runtime reads when
+ * registering the change callback: `debounce` and the trailing `emit:` map.
+ */
+type WatchOptions = {
+    /** Debounce duration in milliseconds */
+    debounce?: number;
+    /** Lifecycle events to emit on update / failure */
+    emit?: {
+        on_message?: string;
+        failure?: string;
+    };
+};
+/**
+ * Watch effect - registers a callback for entity changes.
+ * Emits an event whenever the watched binding changes.
+ * @example ['watch', '@entity.health', 'HEALTH_CHANGED']
+ * @example ['watch', '@entity.status', 'STATUS_UPDATED', { debounce: 100 }]
+ */
+type WatchEffect = ['watch', string, string] | ['watch', string, string, WatchOptions];
+/**
+ * Atomic effect - groups multiple effects into an atomic transaction.
+ * All effects either succeed together or are rolled back.
+ * @example ['atomic', ['set', '@entity.x', 10], ['set', '@entity.y', 20]]
+ * @example ['atomic', ['persist', 'update', 'User', { balance: 100 }], ['emit', 'BALANCE_UPDATED']]
+ */
+type AtomicEffect = ['atomic', ...SExpr[]];
+/**
+ * One layer in an NN architecture description. The set of valid layer kinds
+ * lives in `almadar-std/modules/nn`; here we keep the wire shape generic
+ * enough for the cross-package runtime + Python bridge to round-trip.
+ */
+type NnLayer = {
+    type: string;
+    [key: string]: string | number | boolean | number[] | string[] | undefined;
+};
+/**
+ * Hyperparameters for `train` and `evaluate`. Recursive to allow nested
+ * optimizer / scheduler config blocks without falling back to `unknown`.
+ */
+type NnConfig = {
+    [key: string]: string | number | boolean | string[] | number[] | NnConfig | undefined;
+};
+/**
+ * Forward-pass config: `input` is a binding string (`@payload.input`), and
+ * `on-complete` names the event to fire when the prediction lands.
+ */
+type ForwardConfig = {
+    architecture: NnLayer[];
+    input: string;
+    'on-complete'?: string;
+    config?: NnConfig;
+};
+/**
+ * Training-loop config. `dataset` is a binding string referencing the rows
+ * to train on. Optimizer / loss / scheduler land inside `config`.
+ */
+type TrainConfig = {
+    architecture: NnLayer[];
+    dataset: string;
+    config?: NnConfig;
+    'on-complete'?: string;
+};
+/**
+ * Evaluation config. `metrics` lists named metrics the Python backend
+ * computes (`accuracy`, `precision`, ...).
+ */
+type EvaluateConfig = {
+    architecture: NnLayer[];
+    dataset: string;
+    metrics: string[];
+    config?: NnConfig;
+    'on-complete'?: string;
+};
+/**
+ * Forward effect - runs a neural network forward pass (Python backend).
+ * @example ['forward', 'primary', { architecture: [...], input: '@payload.input', 'on-complete': 'PREDICTION_READY' }]
+ */
+type ForwardEffect = ['forward', string, ForwardConfig];
+/**
+ * Train effect - runs a training loop (Python backend).
+ * @example ['train', { architecture: [...], dataset: '@entity.data', config: { epochs: 10 }, 'on-complete': 'TRAINING_DONE' }]
+ */
+type TrainEffect = ['train', TrainConfig];
+/**
+ * Evaluate effect - runs model evaluation (Python backend).
+ * @example ['evaluate', { architecture: [...], dataset: '@entity.testData', metrics: ['accuracy'], 'on-complete': 'EVAL_DONE' }]
+ */
+type EvaluateEffect = ['evaluate', EvaluateConfig];
+/**
+ * Checkpoint save effect - saves model weights.
+ * @example ['checkpoint/save', '/path/to/model.pt', '@entity.weights']
+ */
+type CheckpointSaveEffect = ['checkpoint/save', string, unknown];
+/**
+ * Checkpoint load effect - loads model weights.
+ * @example ['checkpoint/load', '/path/to/model.pt']
+ */
+type CheckpointLoadEffect = ['checkpoint/load', string];
+/**
+ * Agent effect - invokes an agent/* operator.
+ * Covers all 22 operators in the std-agent category.
+ * @example ['agent/memorize', 'use data-grid for tables', 'preference']
+ * @example ['agent/recall', 'user preferences']
+ * @example ['agent/generate', 'Summarize this schema']
+ */
+type AgentEffect = [`agent/${string}`, ...SExpr[]];
+/**
+ * OS effect - invokes an os/* operator.
+ *
+ * Covers reactive subscriptions to OS / network resources:
+ * - `os/watch-http`, `os/watch-ws`, `os/watch-sse` — long-lived streams
+ *   that fire `on_message` / `failure` events through a trailing
+ *   `EmitConfig` block (see `EmitConfig` for the supported keys).
+ * - `os/read-file`, `os/exec`, etc. — one-shot OS operations.
+ *
+ * @example ['os/watch-http', 'wss://push.example.com', { emit: { on_message: 'PUSH_RECEIVED', failure: 'PUSH_DISCONNECTED' } }]
+ * @example ['os/read-file', '/etc/hosts']
+ */
+type OsEffect = [`os/${string}`, ...SExpr[]];
+/**
+ * Browser effect - invokes a browser/* device operator (client host path).
+ * User-initiated, async, resolves via the standard trailing emit envelope.
+ * Concrete operators (browser/open-file-picker, browser/clipboard-read,
+ * browser/clipboard-write, browser/geolocation-current) and their arity /
+ * payload shapes live in @almadar/std BROWSER_OPERATORS.
+ * @example ['browser/open-file-picker', { multiple: false }, { emit: { success: 'FILES_PICKED', failure: 'PICK_CANCELLED' } }]
+ */
+type BrowserEffect = [`browser/${string}`, ...SExpr[]];
+/**
+ * LLM effect - invokes an llm/* operator (agent path).
+ * @example ['llm/generate', '@entity.request', { emit: { success: 'PLANNED', failure: 'PLAN_FAILED' } }]
+ */
+type LlmEffect = [`llm/${string}`, ...SExpr[]];
+/**
+ * Behavior effect - invokes a behavior/* operator (agent path).
+ * @example ['behavior/instantiate', '@entity.plan', { emit: { failure: 'BUILD_FAILED' } }]
+ */
+type BehaviorEffect = [`behavior/${string}`, ...SExpr[]];
+/**
+ * Validate effect - invokes a validate/* operator (agent path).
+ * @example ['validate/validate', '@entity.schema', { emit: { failure: 'INVALID' } }]
+ */
+type ValidateEffect = [`validate/${string}`, ...SExpr[]];
+/**
+ * Remaining agent-path operator effects: session/* (workspace session ops),
+ * compose/* (schema composition), trace/* (trace emission), memory/*
+ * (agent memory), application/* (app lifecycle). Expression-only namespaces
+ * (array/, math/, object/, str/, …) are deliberately NOT effect heads.
+ * @example ['session/write-spec', '@entity.spec']
+ * @example ['compose/compose-all', { emit: { failure: 'COMPOSE_FAILED' } }]
+ */
+type SessionEffect = [`session/${string}`, ...SExpr[]];
+type ComposeEffect = [`compose/${string}`, ...SExpr[]];
+type TraceEffect = [`trace/${string}`, ...SExpr[]];
+type MemoryEffect = [`memory/${string}`, ...SExpr[]];
+type ApplicationEffect = [`application/${string}`, ...SExpr[]];
+/**
+ * Async delay effect - wait then execute effects.
+ * @example ['async/delay', 2000, ['emit', 'TIMEOUT']]
+ */
+type AsyncDelayEffect = ['async/delay', number | string, ...Effect[]];
+/**
+ * Async debounce effect - debounce then execute effect.
+ * @example ['async/debounce', 300, ['emit', 'SEARCH_COMPLETE']]
+ * @example ['async/debounce', '@entity.debounceMs', ['emit', 'SEARCH_COMPLETE']]
+ */
+type AsyncDebounceEffect = ['async/debounce', number | string, SExpr];
+/**
+ * Async throttle effect - throttle then execute effect.
+ * @example ['async/throttle', 100, ['emit', 'SCROLL_HANDLED']]
+ * @example ['async/throttle', '@entity.throttleMs', ['emit', 'SCROLL_HANDLED']]
+ */
+type AsyncThrottleEffect = ['async/throttle', number | string, SExpr];
+/**
+ * Async interval effect - execute effect at intervals.
+ * @example ['async/interval', 1000, ['emit', 'TICK']]
+ * @example ['async/interval', '@entity.intervalMs', ['emit', 'POLL_TICK']]
+ */
+type AsyncIntervalEffect = ['async/interval', number | string, SExpr];
+/**
+ * Async race effect - first effect to complete wins.
+ * @example ['async/race', ['call', 'api1'], ['call', 'api2']]
+ */
+type AsyncRaceEffect = ['async/race', ...Effect[]];
+/**
+ * Async all effect - wait for all effects to complete.
+ * @example ['async/all', ['call', 'api1'], ['call', 'api2']]
+ */
+type AsyncAllEffect = ['async/all', ...Effect[]];
+/**
+ * Async sequence effect - execute effects in sequence.
+ * @example ['async/sequence', ['call', 'validate'], ['call', 'save']]
+ */
+type AsyncSequenceEffect = ['async/sequence', ...Effect[]];
+/**
+ * Union of all typed effects.
+ * Provides compile-time validation for common effect types.
+ */
+type TypedEffect = RenderUIEffect | NavigateEffect | EmitEffect | SetEffect | PersistEffect | CallServiceEffect | SpawnEffect | DespawnEffect | DoEffect | NotifyEffect | FetchEffect | IfEffect | WhenEffect | LetEffect | LogEffect | WaitEffect | RefEffect | DerefEffect | SwapEffect | WatchEffect | AtomicEffect | AsyncDelayEffect | AsyncDebounceEffect | AsyncThrottleEffect | AsyncIntervalEffect | AsyncRaceEffect | AsyncAllEffect | AsyncSequenceEffect | ForwardEffect | TrainEffect | EvaluateEffect | CheckpointSaveEffect | CheckpointLoadEffect | AgentEffect | OsEffect | BrowserEffect | LlmEffect | BehaviorEffect | ValidateEffect | SessionEffect | ComposeEffect | TraceEffect | MemoryEffect | ApplicationEffect;
+/**
+ * Effect type - typed S-expression format.
+ *
+ * Effects are strongly typed tuples that enforce:
+ * - Valid effect operators (render-ui, emit, set, persist, navigate, call-service)
+ * - Valid UISlots for render-ui
+ * - Valid PatternTypes and props for render-ui
+ * - Correct argument types for each effect
+ *
+ * Available typed effects:
+ * - RenderUIEffect: ['render-ui', UISlot, PatternConfig]
+ * - NavigateEffect: ['navigate', path] or ['navigate', path, params]
+ * - EmitEffect: ['emit', eventName] or ['emit', eventName, payload]
+ * - SetEffect: ['set', binding, value]
+ * - PersistEffect: ['persist', operation, entity, data?]
+ * - CallServiceEffect: ['call-service', serviceName, config]
+ *
+ * @example
+ * ["set", "@entity.health", 100]
+ * ["emit", "PLAYER_DIED", { "playerId": "@entity.id" }]
+ * ["render-ui", "main", { "patternType": "entity-table", "columns": ["name"] }]
+ * ["call-service", "WeatherAPI", { "action": "getWeather", "onSuccess": "OK" }]
+ * ["navigate", "/tasks"]
+ * ["persist", "create", "Task", { "title": "@payload.title" }]
+ */
+type Effect = TypedEffect;
+/**
+ * Schema for Effect - validates S-expression format
+ */
+declare const EffectSchema: z.ZodEffects<z.ZodArray<z.ZodUnknown, "many">, unknown[], unknown[]>;
+type EffectInput = z.input<typeof EffectSchema>;
+/**
+ * Type guard to check if a value is a valid Effect (S-expression).
+ *
+ * Validates that a value conforms to the Effect structure. Effects are
+ * represented as arrays where the first element is a string (effect type)
+ * and subsequent elements are parameters. Used for runtime validation
+ * of effect structures.
+ *
+ * @param {unknown} value - Value to check
+ * @returns {boolean} True if value is a valid Effect, false otherwise
+ *
+ * @example
+ * isEffect(['set', '@entity.health', 100]); // returns true
+ * isEffect('not-an-effect'); // returns false
+ * isEffect([]); // returns false
+ */
+declare function isEffect(value: unknown): value is Effect;
+/**
+ * Alias for isEffect (for clarity when working with S-expressions)
+ */
+declare const isSExprEffect: typeof isEffect;
+/**
+ * Creates a set effect for state updates.
+ *
+ * Generates an effect that sets a binding to a value. Used in state
+ * machine transitions to update entity fields, UI state, or other
+ * mutable data.
+ *
+ * @param {string} binding - Target binding (e.g., '@entity.health')
+ * @param {SExpr} value - Value to set (can be literal or expression)
+ * @returns {Effect} Set effect array
+ *
+ * @example
+ * set('@entity.health', 100); // returns ["set", "@entity.health", 100]
+ * set('@state.loading', false); // returns ["set", "@state.loading", false]
+ */
+declare function set(binding: string, value: SExpr): Effect;
+/**
+ * Creates an emit effect for event dispatching.
+ *
+ * Generates an effect that emits an event with optional payload.
+ * Used in state machine transitions to trigger events that can be
+ * handled by other traits, services, or external systems.
+ *
+ * @param {string} event - Event name to emit
+ * @param {EventPayload} [payload] - Optional event payload
+ * @returns {Effect} Emit effect array
+ *
+ * @example
+ * emit('PLAYER_DIED', { playerId: '@entity.id' }); // returns ["emit", "PLAYER_DIED", { playerId: "@entity.id" }]
+ * emit('GAME_STARTED'); // returns ["emit", "GAME_STARTED"]
+ */
+declare function emit(event: string, payload?: EventPayload): Effect;
+/**
+ * Creates a navigation effect for page routing.
+ *
+ * Generates an effect that navigates to a specified path with optional
+ * parameters. Used in state machine transitions to change pages or
+ * update URL parameters.
+ *
+ * @param {string} path - Target path (e.g., '/tasks')
+ * @param {Record<string, string>} [params] - Optional URL parameters
+ * @returns {NavigateEffect} Navigation effect array
+ *
+ * @example
+ * navigate('/tasks'); // returns ["navigate", "/tasks"]
+ * navigate('/user', { id: '123' }); // returns ["navigate", "/user", { id: "123" }]
+ */
+declare function navigate(path: string): NavigateEffect;
+declare function navigate(path: string, params: Record<string, string>): NavigateEffect;
+/**
+ * Create a render-ui effect
+ * @example ["render-ui", "main", { "patternType": "entity-table", "columns": ["name"] }]
+ */
+declare function renderUI(target: UISlot, pattern: AnyPatternConfig): RenderUIEffect;
+declare function renderUI(target: UISlot, pattern: AnyPatternConfig, props: ResolvedPatternProps): RenderUIEffect;
+/**
+ * Create a persist effect
+ * @example ["persist", "create", "Task", { "title": "@payload.title" }]
+ */
+declare function persist(action: 'create' | 'update', entity: string, data: PersistData): PersistEffect;
+declare function persist(action: 'delete' | 'clear', entity: string, data?: PersistData): PersistEffect;
+/**
+ * Create a call-service effect
+ * @example ["call-service", "stripe", { "service": "stripe", "action": "charge", "onSuccess": "OK", "onError": "ERR" }]
+ */
+declare function callService(serviceName: string, config: CallServiceConfig): CallServiceEffect;
+/**
+ * Create a spawn effect (games)
+ * @example ["spawn", "Bullet", { "x": "@entity.x", "y": "@entity.y" }]
+ */
+declare function spawn(entity: string): SpawnEffect;
+declare function spawn(entity: string, initialState: EntityRow): SpawnEffect;
+/**
+ * Create a despawn effect (games)
+ * @example ["despawn", "@entity.id"]
+ */
+declare function despawn(entityId: string): DespawnEffect;
+/**
+ * Create a do effect (multiple effects)
+ * @example ["do", ["set", "@entity.x", 0], ["set", "@entity.y", 0]]
+ */
+declare function doEffects(...effects: SExpr[]): DoEffect;
+/**
+ * Create a notify effect
+ * @example ["notify", "in_app", "Task created successfully"]
+ */
+declare function notify(channel: 'email' | 'push' | 'sms' | 'in_app', message: string): NotifyEffect;
+declare function notify(channel: 'email' | 'push' | 'sms' | 'in_app', message: string, recipient: string): NotifyEffect;
+/**
+ * Create a ref effect (reactive entity subscription).
+ *
+ * @param {string} binding - Binding or entity name to subscribe to
+ * @param {FetchOptions} [selector] - Optional selector for specific entity
+ * @returns {RefEffect} Ref effect array
+ *
+ * @example
+ * ref('@entity.health'); // returns ["ref", "@entity.health"]
+ * ref('User', { id: '@payload.userId' }); // returns ["ref", "User", { id: "@payload.userId" }]
+ */
+declare function ref(binding: string): RefEffect;
+declare function ref(binding: string, selector: FetchOptions): RefEffect;
+/**
+ * Create a deref effect (snapshot read).
+ *
+ * @param {string} binding - Binding or entity name to read
+ * @param {FetchOptions} [selector] - Optional selector for specific entity
+ * @returns {DerefEffect} Deref effect array
+ *
+ * @example
+ * deref('@entity.health'); // returns ["deref", "@entity.health"]
+ * deref('User', { id: '@payload.userId' }); // returns ["deref", "User", { id: "@payload.userId" }]
+ */
+declare function deref(binding: string): DerefEffect;
+declare function deref(binding: string, selector: FetchOptions): DerefEffect;
+/**
+ * Create a swap! effect (atomic compare-and-swap).
+ *
+ * @param {string} binding - Binding to atomically update
+ * @param {SExpr} transform - Transformation expression applied to the current value
+ * @returns {SwapEffect} Swap effect array
+ *
+ * @example
+ * swap('@entity.counter', ['+', '@entity.counter', 1]);
+ * // returns ["swap!", "@entity.counter", ["+", "@entity.counter", 1]]
+ */
+declare function swap(binding: string, transform: SExpr): SwapEffect;
+/**
+ * Create a watch effect (entity change callback).
+ *
+ * @example
+ * watch('@entity.health', 'HEALTH_CHANGED');
+ * watch('@entity.status', 'STATUS_UPDATED', { debounce: 100 });
+ */
+declare function watch(binding: string, event: string): WatchEffect;
+declare function watch(binding: string, event: string, options: WatchOptions): WatchEffect;
+/**
+ * Create an atomic effect (transaction group).
+ *
+ * @param {...SExpr[]} effects - Effects to execute atomically
+ * @returns {AtomicEffect} Atomic effect array
+ *
+ * @example
+ * atomic(['set', '@entity.x', 10], ['set', '@entity.y', 20]);
+ * // returns ["atomic", ["set", "@entity.x", 10], ["set", "@entity.y", 20]]
+ */
+declare function atomic(...effects: SExpr[]): AtomicEffect;
+/** Resolved pattern props for render-ui effects at runtime. Recursive for nested pattern configs. */
+type ResolvedPatternProps = {
+    [prop: string]: string | number | boolean | null | undefined | ResolvedPatternProps | ResolvedPatternProps[];
+};
+/** A node in a render-ui effect tree. */
+interface RenderUINode {
+    type: string;
+    props?: ResolvedPatternProps;
+    /** Static child nodes and/or dynamic-collection map entries. A
+     *  {@link RenderChildrenMap} entry expands at render time into resolved
+     *  `RenderUINode`s, so components always receive a flat, fully-resolved list. */
+    children?: Array<RenderUINode | RenderChildrenMap>;
+    content?: string;
+    entity?: string;
+    renderItem?: RenderUINode;
+}
+
+export { ENTITY_ROLES as $, type AnyPatternConfig as A, type AssetDimension as B, AssetDimensionSchema as C, AssetSchema as D, type EntityField as E, type FieldValue as F, type AssetUrl as G, type AtomicEffect as H, type BehaviorEffect as I, type JsonValue as J, CAMERA_MODES as K, type CallServiceConfig as L, type CallServiceEffect as M, type Camera as N, type OrbitalId as O, type PageId as P, type CameraMode as Q, type RelationConfig as R, CameraModeSchema as S, type TraitId as T, CameraSchema as U, type CheckpointLoadEffect as V, type CheckpointSaveEffect as W, type ComposeEffect as X, type DerefEffect as Y, type DespawnEffect as Z, type DoEffect as _, type EntityPersistence as a, RelationConfigSchema as a$, type EffectInput as a0, EffectSchema as a1, type EmitConfig as a2, type EmitEffect as a3, type EntityData as a4, type EntityFieldInput as a5, EntityFieldSchema as a6, EntityIdSchema as a7, EntityPersistenceSchema as a8, type EntityRole as a9, LedgerKindSchema as aA, type LlmEffect as aB, type LogEffect as aC, type McpServiceDef as aD, McpServiceDefSchema as aE, type MemoryEffect as aF, type NavigateEffect as aG, type NnConfig as aH, type NnLayer as aI, type NotifyEffect as aJ, type OrbitalEntity as aK, type OrbitalEntityInput as aL, OrbitalEntitySchema as aM, OrbitalIdSchema as aN, type OsEffect as aO, PATTERN_TYPES as aP, PageIdSchema as aQ, type PaletteEntryId as aR, PaletteEntryIdSchema as aS, type PatternConfig as aT, type PatternProps as aU, type PatternPropsMap as aV, type PatternType as aW, type PersistData as aX, type PersistEffect as aY, type PersistEmitConfig as aZ, type RefEffect as a_, EntityRoleSchema as aa, EntitySchema as ab, type EntityWith as ac, type EnumEntityField as ad, type EvaluateConfig as ae, type EvaluateEffect as af, EventIdSchema as ag, type FetchEffect as ah, type FetchOptions as ai, type FetchResult as aj, type Field as ak, type FieldFormat as al, FieldFormatSchema as am, FieldSchema as an, type FieldType as ao, FieldTypeSchema as ap, type ForwardConfig as aq, type ForwardEffect as ar, type IdForKind as as, type IdKind as at, type IdentityLedger as au, IdentityLedgerSchema as av, type JsonObject as aw, type LedgerEntry as ax, LedgerEntrySchema as ay, type LedgerKind as az, type EventId as b, type VisualStyle as b$, type RelationEntityField as b0, type RenderBinding as b1, type RenderChildrenMap as b2, type RenderItemLambda as b3, type RenderUIEffect as b4, type RenderUINode as b5, type ResolvedPatternProps as b6, type RestAuthConfig as b7, RestAuthConfigSchema as b8, type RestServiceDef as b9, type SocketServiceDef as bA, SocketServiceDefSchema as bB, type SpawnEffect as bC, type SpriteDirection as bD, SpriteDirectionSchema as bE, type SpriteSheetAtlas as bF, type SpriteSheetAtlasInput as bG, SpriteSheetAtlasSchema as bH, type SubTexture as bI, SubTextureSchema as bJ, type SwapEffect as bK, type TextureAtlas as bL, TextureAtlasSchema as bM, type ThemeId as bN, ThemeIdSchema as bO, type Tilesheet as bP, TilesheetSchema as bQ, type TraceEffect as bR, type TrainConfig as bS, type TrainEffect as bT, TraitIdSchema as bU, type TypedEffect as bV, type UISlot as bW, UISlotSchema as bX, UI_SLOTS as bY, VISUAL_STYLES as bZ, type ValidateEffect as b_, RestServiceDefSchema as ba, SERVICE_TYPES as bb, SPRITE_DIRECTIONS as bc, type ScalarEntityField as bd, type ScenePos as be, ScenePosSchema as bf, type SemanticAssetRef as bg, type SemanticAssetRefInput as bh, SemanticAssetRefSchema as bi, type ServiceDefinition as bj, ServiceDefinitionSchema as bk, type ServiceId as bl, ServiceIdSchema as bm, type ServiceParams as bn, type ServiceParamsValue as bo, type ServiceRef as bp, type ServiceRefObject as bq, ServiceRefObjectSchema as br, ServiceRefSchema as bs, ServiceRefStringSchema as bt, type ServiceType as bu, ServiceTypeSchema as bv, type SessionEffect as bw, type SetEffect as bx, type SocketEvents as by, SocketEventsSchema as bz, type Effect as c, VisualStyleSchema as c0, type WatchEffect as c1, type WatchOptions as c2, asEntityId as c3, asEventId as c4, asOrbitalId as c5, asPageId as c6, asPaletteEntryId as c7, asServiceId as c8, asThemeId as c9, isRestService as cA, isRuntimeEntity as cB, isSExprEffect as cC, isServiceId as cD, isServiceReference as cE, isServiceReferenceObject as cF, isSocketService as cG, isThemeId as cH, isTraitId as cI, isValidPatternType as cJ, ledgerCurName as cK, ledgerRename as cL, ledgerResolveName as cM, mintId as cN, navigate as cO, notify as cP, parseAssetKey as cQ, parseServiceRef as cR, persist as cS, persistenceModeAllowsOverrides as cT, ref as cU, renderUI as cV, set as cW, spawn as cX, swap as cY, validateAssetAnimations as cZ, watch as c_, asTraitId as ca, atomic as cb, callService as cc, createAssetKey as cd, deref as ce, deriveCollection as cf, despawn as cg, doEffects as ch, emit as ci, findService as cj, getDefaultAnimationsForRole as ck, getServiceNames as cl, hasService as cm, idKindOf as cn, idPrefix as co, isEffect as cp, isEntityId as cq, isEventId as cr, isFieldValue as cs, isJsonArray as ct, isJsonObject as cu, isJsonPrimitive as cv, isMcpService as cw, isOrbitalId as cx, isPageId as cy, isPaletteEntryId as cz, type EntityId as d, type Entity as e, type ToolArgs as f, type EntityRow as g, ANIMATION_NAMES as h, ASSET_ASPECTS as i, ASSET_DIMENSIONS as j, type AgentEffect as k, type AnimationDef as l, type AnimationDefInput as m, AnimationDefSchema as n, type AnimationName as o, AnimationNameSchema as p, type ApplicationEffect as q, type ArrayEntityField as r, type Asset as s, type AssetAspect as t, AssetAspectSchema as u, type AssetCatalog as v, type AssetCatalogEntry as w, type AssetCatalogEntryInput as x, AssetCatalogEntrySchema as y, AssetCatalogSchema as z };