@almadar/runtime 2.5.0 → 2.6.1

package/dist/index.d.ts

@@ -1,11 +1,11 @@
-import { B as BindingContext, T as TraitState, a as TraitDefinition, R as RuntimeConfig, b as TransitionObserver, c as TransitionResult, E as EffectHandlers, d as EffectContext, e as ExecutionEnvironment, f as EffectResult } from './types-BrbvZxzX.js';
-export { g as Effect, h as EventListener, H as HANDLER_MANIFEST, I as IEventBus, i as RuntimeEvent, U as Unsubscribe } from './types-BrbvZxzX.js';
-export { E as EntitySharingMap, a as EventBus, b as EventNamespaceMap, O as OrbitalEventRequest, c as OrbitalEventResponse, d as OrbitalServerRuntimeConfig, P as PersistenceAdapter, e as PreprocessOptions, f as PreprocessResult, g as PreprocessedSchema, R as RuntimeOrbital, h as RuntimeOrbitalSchema, i as RuntimeTrait, j as getIsolatedCollectionName, k as getNamespacedEvent, l as isNamespacedEvent, p as parseNamespacedEvent, m as preprocessSchema } from './OrbitalServerRuntime-Bel-jQ_o.js';
+import { B as BindingContext, P as PatternProps, E as EffectHandlers, a as EffectContext, b as ExecutionEnvironment, c as EffectResult, T as TraitDefinition } from './types-DYcUvi4H.js';
+export { d as Effect, e as EventListener, H as HANDLER_MANIFEST, I as IEventBus, R as RuntimeConfig, f as RuntimeEvent, g as TraitState, h as TransitionObserver, i as TransitionResult, U as Unsubscribe } from './types-DYcUvi4H.js';
+export { E as EntitySharingMap, a as EventBus, b as EventNamespaceMap, O as OrbitalEventRequest, c as OrbitalEventResponse, d as OrbitalServerRuntimeConfig, P as PersistenceAdapter, e as PreprocessOptions, f as PreprocessResult, g as PreprocessedSchema, h as ProcessEventOptions, R as RegisteredOrbital, i as RuntimeOrbital, j as RuntimeOrbitalSchema, k as RuntimeTrait, S as StateMachineManager, l as createInitialTraitState, m as findInitialState, n as findTransition, o as getIsolatedCollectionName, p as getNamespacedEvent, q as isNamespacedEvent, r as normalizeEventKey, s as parseNamespacedEvent, t as preprocessSchema, u as processEvent } from './OrbitalServerRuntime-B-QeKtKd.js';
 import { EvaluationContext } from '@almadar/evaluator';
 export { EvaluationContext, createMinimalContext } from '@almadar/evaluator';
+import { EventPayload, EntityRow } from '@almadar/core';
 export { ServerBridgeConfig, ServerBridgeState } from './ServerBridge.js';
 import 'express';
-import '@almadar/core';
 
 /**
  * BindingResolver - Platform-Agnostic Binding Resolution
@@ -36,7 +36,7 @@ import '@almadar/core';
  * // { title: 'Project Alpha', total: 52 }
  * ```
  */
-declare function interpolateProps(props: Record<string, unknown>, ctx: EvaluationContext): Record<string, unknown>;
+declare function interpolateProps(props: PatternProps, ctx: EvaluationContext): PatternProps;
 /**
  * Interpolate a single value.
  */
@@ -57,168 +57,6 @@ declare function extractBindings(value: unknown): string[];
  */
 declare function createContextFromBindings(bindings: BindingContext, strictBindings?: boolean): EvaluationContext;
 
-/**
- * StateMachineCore - Platform-Agnostic State Machine Logic
- *
- * Pure TypeScript implementation of trait state machine execution.
- * Extracts the core logic from useTraitStateMachine for use on
- * both client and server.
- *
- * @packageDocumentation
- */
-
-/**
- * Find the initial state for a trait definition.
- */
-declare function findInitialState(trait: TraitDefinition): string;
-/**
- * Create initial trait state for a trait definition.
- */
-declare function createInitialTraitState(trait: TraitDefinition): TraitState;
-/**
- * Find a matching transition from the current state for the given event.
- */
-declare function findTransition(trait: TraitDefinition, currentState: string, eventKey: string): TraitDefinition['transitions'][0] | undefined;
-/**
- * Normalize event key - strip UI: prefix if present.
- */
-declare function normalizeEventKey(eventKey: string): string;
-/**
- * Options for processing an event through the state machine.
- */
-interface ProcessEventOptions {
-    /** Current trait state */
-    traitState: TraitState;
-    /** Trait definition */
-    trait: TraitDefinition;
-    /** Event key to process */
-    eventKey: string;
-    /** Event payload */
-    payload?: Record<string, unknown>;
-    /** Entity data for binding resolution */
-    entityData?: Record<string, unknown>;
-    /**
-     * Guard evaluation error handling mode. (RCG-02)
-     * - "permissive": Guard errors allow the transition (default, backwards-compatible)
-     * - "strict": Guard errors block the transition
-     */
-    guardMode?: "strict" | "permissive";
-    /**
-     * When true, log warnings when bindings resolve to undefined. (RCG-01)
-     */
-    strictBindings?: boolean;
-}
-/**
- * Process an event through a trait's state machine.
- *
- * This is a pure function that:
- * 1. Finds matching transitions
- * 2. Evaluates guards
- * 3. Returns the transition result (but does not execute effects)
- *
- * @returns TransitionResult with effects to execute
- *
- * @example
- * ```ts
- * const result = processEvent({
- *   traitState: { traitName: 'Cart', currentState: 'empty', ... },
- *   trait: cartTraitDefinition,
- *   eventKey: 'ADD_ITEM',
- *   payload: { productId: '123' },
- * });
- *
- * if (result.executed) {
- *   // Execute effects
- *   for (const effect of result.effects) {
- *     effectExecutor.execute(effect);
- *   }
- *   // Update state
- *   traitState.currentState = result.newState;
- * }
- * ```
- */
-declare function processEvent(options: ProcessEventOptions): TransitionResult;
-declare class StateMachineManager {
-    private traits;
-    private states;
-    private config;
-    private observer?;
-    private queues;
-    private processing;
-    constructor(traits?: TraitDefinition[], config?: RuntimeConfig, observer?: TransitionObserver);
-    /**
-     * Set the transition observer for runtime verification.
-     * Wire this to `verificationRegistry.recordTransition()` to enable
-     * automatic verification tracking.
-     */
-    setObserver(observer: TransitionObserver): void;
-    /**
-     * Add a trait to the manager.
-     */
-    addTrait(trait: TraitDefinition): void;
-    /**
-     * Remove a trait from the manager.
-     */
-    removeTrait(traitName: string): void;
-    /**
-     * Get current state for a trait.
-     */
-    getState(traitName: string): TraitState | undefined;
-    /**
-     * Get all current states.
-     */
-    getAllStates(): Map<string, TraitState>;
-    /**
-     * Check if a trait can handle an event from its current state.
-     */
-    canHandleEvent(traitName: string, eventKey: string): boolean;
-    /**
-     * Send an event to all traits.
-     *
-     * @returns Array of transition results (one per trait that had a matching transition)
-     */
-    sendEvent(eventKey: string, payload?: Record<string, unknown>, entityData?: Record<string, unknown>): Array<{
-        traitName: string;
-        result: TransitionResult;
-    }>;
-    /**
-     * Enqueue an event into every trait's per-trait queue.
-     *
-     * Events are not processed immediately. Call `drainQueue()` for each
-     * trait to process them sequentially (actor-model guarantee: one event
-     * at a time per trait, effects fully awaited before the next event).
-     */
-    enqueueEvent(eventKey: string, payload?: Record<string, unknown>, entityData?: Record<string, unknown>): void;
-    /**
-     * Drain a single trait's event queue, processing events sequentially.
-     *
-     * This is the core actor loop: each event is fully processed (including
-     * awaiting all effects) before the next event is dequeued. If the queue
-     * is already being drained for this trait, this call is a no-op (the
-     * running drain will pick up newly enqueued events).
-     *
-     * @param traitName - Which trait's queue to drain
-     * @param executeEffects - Async callback to run effects for a successful transition
-     */
-    drainQueue(traitName: string, executeEffects: (traitName: string, result: TransitionResult, payload?: Record<string, unknown>) => Promise<void>): Promise<void>;
-    /**
-     * Check whether a trait's queue is currently being drained.
-     */
-    isProcessing(traitName: string): boolean;
-    /**
-     * Get the number of pending events in a trait's queue.
-     */
-    getQueueLength(traitName: string): number;
-    /**
-     * Reset a trait to its initial state.
-     */
-    resetTrait(traitName: string): void;
-    /**
-     * Reset all traits to initial states.
-     */
-    resetAll(): void;
-}
-
 /**
  * EffectExecutor - Platform-Agnostic Effect Dispatch
  *
@@ -342,7 +180,7 @@ declare function createTestExecutor(overrides?: Partial<EffectHandlers>): Effect
  * Minimal event bus interface required by the factory.
  */
 interface ClientEventBus {
-    emit: (type: string, payload?: Record<string, unknown>) => void;
+    emit: (type: string, payload?: EventPayload) => void;
 }
 /**
  * Slot setter interface for render-ui effects.
@@ -350,7 +188,7 @@ interface ClientEventBus {
  */
 interface SlotSetter {
     /** Accumulate a pattern into the pending slot map */
-    addPattern: (slot: string, pattern: unknown, props?: Record<string, unknown>) => void;
+    addPattern: (slot: string, pattern: unknown, props?: PatternProps) => void;
     /** Mark a slot for clearing */
     clearSlot: (slot: string) => void;
 }
@@ -363,7 +201,9 @@ interface CreateClientEffectHandlersOptions {
     /** Slot setter for render-ui effects */
     slotSetter: SlotSetter;
     /** Navigate function for navigate effects */
-    navigate?: (path: string, params?: Record<string, unknown>) => void;
+    navigate?: (path: string, params?: {
+        [key: string]: string;
+    }) => void;
     /** Notify function for notification effects */
     notify?: (message: string, type: 'success' | 'error' | 'warning' | 'info') => void;
 }
@@ -402,7 +242,7 @@ declare function createClientEffectHandlers(options: CreateClientEffectHandlersO
 
 interface OsHandlerContext {
     /** Emit an event on the EventBus */
-    emitEvent: (type: string, payload: Record<string, unknown>) => void;
+    emitEvent: (type: string, payload: EventPayload) => void;
     /** Working directory for file watching (defaults to process.cwd()) */
     cwd?: string;
 }
@@ -431,7 +271,7 @@ interface EntitySchema {
     name: string;
     fields: EntityField[];
     /** Pre-authored instance data from the schema (used instead of faker generation) */
-    seedData?: Record<string, unknown>[];
+    seedData?: EntityRow[];
 }
 interface MockPersistenceConfig {
     /** Seed for deterministic generation */
@@ -506,4 +346,4 @@ declare function validatePayloadShapes(traits: TraitDefinition[], emits: Map<str
  */
 declare function buildEmitsFromTraits(traits: TraitDefinition[], explicitEmits?: Map<string, EmitDeclaration[]>): Map<string, EmitDeclaration[]>;
 
-export { BindingContext, type ClientEventBus, type CreateClientEffectHandlersOptions, EffectContext, EffectExecutor, type EffectExecutorOptions, EffectHandlers, EffectResult, type EntityField, type EntitySchema, ExecutionEnvironment, type MockPersistenceConfig, type OsHandlerContext, type OsHandlerResult, type PayloadMismatch, type ProcessEventOptions, RuntimeConfig, type SlotSetter, StateMachineManager, TraitDefinition, TraitState, TransitionObserver, TransitionResult, buildEmitsFromTraits, containsBindings, createClientEffectHandlers, createContextFromBindings, createInitialTraitState, createTestExecutor, extractBindings, findInitialState, findTransition, interpolateProps, interpolateValue, normalizeEventKey, processEvent, validatePayloadShapes };
+export { BindingContext, type ClientEventBus, type CreateClientEffectHandlersOptions, EffectContext, EffectExecutor, type EffectExecutorOptions, EffectHandlers, EffectResult, type EntityField, type EntitySchema, ExecutionEnvironment, type MockPersistenceConfig, type OsHandlerContext, type OsHandlerResult, type PayloadMismatch, type SlotSetter, TraitDefinition, buildEmitsFromTraits, containsBindings, createClientEffectHandlers, createContextFromBindings, createTestExecutor, extractBindings, interpolateProps, interpolateValue, validatePayloadShapes };

package/dist/index.js

@@ -1,4 +1,4 @@
-export { EffectExecutor, EventBus, HANDLER_MANIFEST, StateMachineManager, containsBindings, createContextFromBindings, createInitialTraitState, createMinimalContext, createTestExecutor, extractBindings, findInitialState, findTransition, getIsolatedCollectionName, getNamespacedEvent, interpolateProps, interpolateValue, isNamespacedEvent, normalizeEventKey, parseNamespacedEvent, preprocessSchema, processEvent } from './chunk-ICTFAD3I.js';
+export { EffectExecutor, EventBus, HANDLER_MANIFEST, StateMachineManager, containsBindings, createContextFromBindings, createInitialTraitState, createMinimalContext, createTestExecutor, extractBindings, findInitialState, findTransition, getIsolatedCollectionName, getNamespacedEvent, interpolateProps, interpolateValue, isNamespacedEvent, normalizeEventKey, parseNamespacedEvent, preprocessSchema, processEvent } from './chunk-ESNML4B4.js';
 
 // src/ClientEffectHandlers.ts
 function createClientEffectHandlers(options) {

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/ClientEffectHandlers.ts","../src/PayloadValidator.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Client Effect Handlers Factory\n *\n * Creates the standard effect handler set for client-side trait execution.\n * Platform-agnostic — works with any UI framework that provides the required interfaces.\n *\n * @packageDocumentation\n */\n\nimport type { EffectHandlers } from './types.js';\n\n// ============================================================================\n// Types\n// ============================================================================\n\n/**\n * Minimal event bus interface required by the factory.\n */\nexport interface ClientEventBus {\n    emit: (type: string, payload?: Record<string, unknown>) => void;\n}\n\n/**\n * Slot setter interface for render-ui effects.\n * The factory doesn't know about React state — it just calls this function.\n */\nexport interface SlotSetter {\n    /** Accumulate a pattern into the pending slot map */\n    addPattern: (slot: string, pattern: unknown, props?: Record<string, unknown>) => void;\n    /** Mark a slot for clearing */\n    clearSlot: (slot: string) => void;\n}\n\n/**\n * Options for creating client effect handlers.\n */\nexport interface CreateClientEffectHandlersOptions {\n    /** Event bus for emit effects */\n    eventBus: ClientEventBus;\n    /** Slot setter for render-ui effects */\n    slotSetter: SlotSetter;\n    /** Navigate function for navigate effects */\n    navigate?: (path: string, params?: Record<string, unknown>) => void;\n    /** Notify function for notification effects */\n    notify?: (message: string, type: 'success' | 'error' | 'warning' | 'info') => void;\n}\n\n// ============================================================================\n// Factory\n// ============================================================================\n\n/**\n * Create client-side effect handlers for trait state machine execution.\n *\n * Client handles: emit, renderUI, navigate, notify\n * Server handles: persist, set, callService (logged as warnings on client)\n *\n * @example\n * ```ts\n * const handlers = createClientEffectHandlers({\n *   eventBus,\n *   slotSetter: {\n *     addPattern: (slot, pattern, props) => pendingSlots.get(slot)?.push({ pattern, props }),\n *     clearSlot: (slot) => pendingSlots.set(slot, []),\n *   },\n *   navigate: (path) => router.push(path),\n *   notify: (msg, type) => toast[type](msg),\n * });\n * ```\n */\nexport function createClientEffectHandlers(\n    options: CreateClientEffectHandlersOptions\n): EffectHandlers {\n    const { eventBus, slotSetter, navigate, notify } = options;\n\n    return {\n        emit: (event: string, payload?: Record<string, unknown>) => {\n            const prefixedEvent = event.startsWith('UI:') ? event : `UI:${event}`;\n            eventBus.emit(prefixedEvent, { payload });\n        },\n\n        persist: async () => {\n            console.warn('[ClientEffectHandlers] persist is server-side only, ignored on client');\n        },\n\n        set: () => {\n            console.warn('[ClientEffectHandlers] set is server-side only, ignored on client');\n        },\n\n        callService: async () => {\n            console.warn('[ClientEffectHandlers] callService is server-side only, ignored on client');\n            return {};\n        },\n\n        renderUI: (slot: string, pattern: unknown, props?: Record<string, unknown>) => {\n            if (pattern === null) {\n                slotSetter.clearSlot(slot);\n                return;\n            }\n            slotSetter.addPattern(slot, pattern, props);\n        },\n\n        navigate: navigate ?? ((path: string) => {\n            console.warn('[ClientEffectHandlers] No navigate handler, ignoring:', path);\n        }),\n\n        notify: notify ?? ((msg: string, type?: string) => {\n            console.log(`[ClientEffectHandlers] notify (${type}):`, msg);\n        }),\n    };\n}\n","/**\n * PayloadValidator - Cross-Trait Payload Shape Validation (RCG-10)\n *\n * Validates that listener `payloadMapping` references match the emitter's\n * payload field names. Catches mismatches like `@payload.task_id` when the\n * emitter defines `taskId`.\n *\n * @packageDocumentation\n */\n\nimport type { TraitDefinition } from './types.js';\n\n// ============================================================================\n// Types\n// ============================================================================\n\n/**\n * Emit declaration from a trait.\n */\ninterface EmitDeclaration {\n    event: string;\n    payload?: Array<{ name: string; type?: string }>;\n}\n\n/**\n * Payload validation error.\n */\nexport interface PayloadMismatch {\n    /** Listening trait name */\n    listenerTrait: string;\n    /** Emitting trait name */\n    emitterTrait: string;\n    /** Event name */\n    event: string;\n    /** The payload field referenced in the listener's payloadMapping */\n    referencedField: string;\n    /** Available fields from the emitter's payload declaration */\n    availableFields: string[];\n}\n\n// ============================================================================\n// Validation\n// ============================================================================\n\n/**\n * Validate that all listener payloadMapping references match emitter payload fields.\n *\n * @param traits - All trait definitions in the schema\n * @param emits - Emit declarations per trait (traitName → EmitDeclaration[])\n * @returns Array of payload mismatches (empty if all valid)\n *\n * @example\n * ```ts\n * const mismatches = validatePayloadShapes(traits, emitsMap);\n * for (const m of mismatches) {\n *   console.warn(\n *     `Trait \"${m.listenerTrait}\" references @payload.${m.referencedField} ` +\n *     `for event \"${m.event}\" but emitter \"${m.emitterTrait}\" only declares: ` +\n *     `${m.availableFields.join(', ')}`\n *   );\n * }\n * ```\n */\nexport function validatePayloadShapes(\n    traits: TraitDefinition[],\n    emits: Map<string, EmitDeclaration[]>\n): PayloadMismatch[] {\n    const mismatches: PayloadMismatch[] = [];\n\n    // Build event→emitter lookup: event name → { traitName, payload fields }\n    const emitIndex = new Map<string, { traitName: string; fields: string[] }>();\n    for (const [traitName, declarations] of emits) {\n        for (const decl of declarations) {\n            const fields = decl.payload?.map((p) => p.name) ?? [];\n            emitIndex.set(decl.event, { traitName, fields });\n        }\n    }\n\n    // Check each listener's payloadMapping references\n    for (const trait of traits) {\n        if (!trait.listens) continue;\n\n        for (const listener of trait.listens) {\n            const emitter = emitIndex.get(listener.event);\n            if (!emitter) continue; // No emitter found — separate validation concern\n\n            if (!listener.payloadMapping) continue;\n\n            // Extract @payload.X references from payloadMapping values\n            const payloadRefs = extractPayloadReferences(listener.payloadMapping);\n\n            for (const ref of payloadRefs) {\n                if (!emitter.fields.includes(ref)) {\n                    mismatches.push({\n                        listenerTrait: trait.name,\n                        emitterTrait: emitter.traitName,\n                        event: listener.event,\n                        referencedField: ref,\n                        availableFields: emitter.fields,\n                    });\n                }\n            }\n        }\n    }\n\n    return mismatches;\n}\n\n/**\n * Extract payload field references from a payloadMapping object.\n * Finds all `@payload.fieldName` patterns and returns the field names.\n */\nfunction extractPayloadReferences(mapping: Record<string, unknown>): string[] {\n    const refs: string[] = [];\n\n    function collect(value: unknown): void {\n        if (typeof value === 'string') {\n            const match = value.match(/^@payload\\.(\\w+)$/);\n            if (match) {\n                refs.push(match[1]);\n            }\n        } else if (typeof value === 'object' && value !== null) {\n            if (Array.isArray(value)) {\n                value.forEach(collect);\n            } else {\n                Object.values(value as Record<string, unknown>).forEach(collect);\n            }\n        }\n    }\n\n    Object.values(mapping).forEach(collect);\n    return [...new Set(refs)];\n}\n\n/**\n * Build emit declarations map from trait definitions.\n * Extracts emits from transitions that use the `emit` effect.\n *\n * Note: This is a heuristic — it parses emit effects from transitions.\n * For full accuracy, the schema should include explicit `emits` declarations.\n */\nexport function buildEmitsFromTraits(\n    traits: TraitDefinition[],\n    explicitEmits?: Map<string, EmitDeclaration[]>\n): Map<string, EmitDeclaration[]> {\n    // Start with explicit emits if provided\n    const result = new Map<string, EmitDeclaration[]>(explicitEmits ?? []);\n\n    for (const trait of traits) {\n        if (result.has(trait.name)) continue; // Explicit declarations take precedence\n\n        const emitDecls: EmitDeclaration[] = [];\n        for (const transition of trait.transitions) {\n            if (!transition.effects) continue;\n\n            for (const effect of transition.effects) {\n                if (!Array.isArray(effect)) continue;\n                if (effect[0] === 'emit' && typeof effect[1] === 'string') {\n                    const event = effect[1] as string;\n                    // Payload is in effect[2] if present\n                    const payloadObj = effect[2] as Record<string, unknown> | undefined;\n                    const payload = payloadObj\n                        ? Object.keys(payloadObj).map((name) => ({ name }))\n                        : undefined;\n\n                    // Avoid duplicates\n                    if (!emitDecls.some((d) => d.event === event)) {\n                        emitDecls.push({ event, payload });\n                    }\n                }\n            }\n        }\n\n        if (emitDecls.length > 0) {\n            result.set(trait.name, emitDecls);\n        }\n    }\n\n    return result;\n}\n"]}
+{"version":3,"sources":["../src/ClientEffectHandlers.ts","../src/PayloadValidator.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Client Effect Handlers Factory\n *\n * Creates the standard effect handler set for client-side trait execution.\n * Platform-agnostic — works with any UI framework that provides the required interfaces.\n *\n * @packageDocumentation\n */\n\nimport type { EffectHandlers, EventPayload, PatternProps } from './types.js';\n\n// ============================================================================\n// Types\n// ============================================================================\n\n/**\n * Minimal event bus interface required by the factory.\n */\nexport interface ClientEventBus {\n    emit: (type: string, payload?: EventPayload) => void;\n}\n\n/**\n * Slot setter interface for render-ui effects.\n * The factory doesn't know about React state — it just calls this function.\n */\nexport interface SlotSetter {\n    /** Accumulate a pattern into the pending slot map */\n    addPattern: (slot: string, pattern: unknown, props?: PatternProps) => void;\n    /** Mark a slot for clearing */\n    clearSlot: (slot: string) => void;\n}\n\n/**\n * Options for creating client effect handlers.\n */\nexport interface CreateClientEffectHandlersOptions {\n    /** Event bus for emit effects */\n    eventBus: ClientEventBus;\n    /** Slot setter for render-ui effects */\n    slotSetter: SlotSetter;\n    /** Navigate function for navigate effects */\n    navigate?: (path: string, params?: { [key: string]: string }) => void;\n    /** Notify function for notification effects */\n    notify?: (message: string, type: 'success' | 'error' | 'warning' | 'info') => void;\n}\n\n// ============================================================================\n// Factory\n// ============================================================================\n\n/**\n * Create client-side effect handlers for trait state machine execution.\n *\n * Client handles: emit, renderUI, navigate, notify\n * Server handles: persist, set, callService (logged as warnings on client)\n *\n * @example\n * ```ts\n * const handlers = createClientEffectHandlers({\n *   eventBus,\n *   slotSetter: {\n *     addPattern: (slot, pattern, props) => pendingSlots.get(slot)?.push({ pattern, props }),\n *     clearSlot: (slot) => pendingSlots.set(slot, []),\n *   },\n *   navigate: (path) => router.push(path),\n *   notify: (msg, type) => toast[type](msg),\n * });\n * ```\n */\nexport function createClientEffectHandlers(\n    options: CreateClientEffectHandlersOptions\n): EffectHandlers {\n    const { eventBus, slotSetter, navigate, notify } = options;\n\n    return {\n        emit: (event: string, payload?: EventPayload) => {\n            const prefixedEvent = event.startsWith('UI:') ? event : `UI:${event}`;\n            eventBus.emit(prefixedEvent, { payload });\n        },\n\n        persist: async () => {\n            console.warn('[ClientEffectHandlers] persist is server-side only, ignored on client');\n        },\n\n        set: () => {\n            console.warn('[ClientEffectHandlers] set is server-side only, ignored on client');\n        },\n\n        callService: async () => {\n            console.warn('[ClientEffectHandlers] callService is server-side only, ignored on client');\n            return {};\n        },\n\n        renderUI: (slot: string, pattern: unknown, props?: PatternProps) => {\n            if (pattern === null) {\n                slotSetter.clearSlot(slot);\n                return;\n            }\n            slotSetter.addPattern(slot, pattern, props);\n        },\n\n        navigate: navigate ?? ((path: string) => {\n            console.warn('[ClientEffectHandlers] No navigate handler, ignoring:', path);\n        }),\n\n        notify: notify ?? ((msg: string, type?: string) => {\n            console.log(`[ClientEffectHandlers] notify (${type}):`, msg);\n        }),\n    };\n}\n","/**\n * PayloadValidator - Cross-Trait Payload Shape Validation (RCG-10)\n *\n * Validates that listener `payloadMapping` references match the emitter's\n * payload field names. Catches mismatches like `@payload.task_id` when the\n * emitter defines `taskId`.\n *\n * @packageDocumentation\n */\n\nimport type { TraitDefinition, EventPayload } from './types.js';\n\n// ============================================================================\n// Types\n// ============================================================================\n\n/**\n * Emit declaration from a trait.\n */\ninterface EmitDeclaration {\n    event: string;\n    payload?: Array<{ name: string; type?: string }>;\n}\n\n/**\n * Payload validation error.\n */\nexport interface PayloadMismatch {\n    /** Listening trait name */\n    listenerTrait: string;\n    /** Emitting trait name */\n    emitterTrait: string;\n    /** Event name */\n    event: string;\n    /** The payload field referenced in the listener's payloadMapping */\n    referencedField: string;\n    /** Available fields from the emitter's payload declaration */\n    availableFields: string[];\n}\n\n// ============================================================================\n// Validation\n// ============================================================================\n\n/**\n * Validate that all listener payloadMapping references match emitter payload fields.\n *\n * @param traits - All trait definitions in the schema\n * @param emits - Emit declarations per trait (traitName → EmitDeclaration[])\n * @returns Array of payload mismatches (empty if all valid)\n *\n * @example\n * ```ts\n * const mismatches = validatePayloadShapes(traits, emitsMap);\n * for (const m of mismatches) {\n *   console.warn(\n *     `Trait \"${m.listenerTrait}\" references @payload.${m.referencedField} ` +\n *     `for event \"${m.event}\" but emitter \"${m.emitterTrait}\" only declares: ` +\n *     `${m.availableFields.join(', ')}`\n *   );\n * }\n * ```\n */\nexport function validatePayloadShapes(\n    traits: TraitDefinition[],\n    emits: Map<string, EmitDeclaration[]>\n): PayloadMismatch[] {\n    const mismatches: PayloadMismatch[] = [];\n\n    // Build event→emitter lookup: event name → { traitName, payload fields }\n    const emitIndex = new Map<string, { traitName: string; fields: string[] }>();\n    for (const [traitName, declarations] of emits) {\n        for (const decl of declarations) {\n            const fields = decl.payload?.map((p) => p.name) ?? [];\n            emitIndex.set(decl.event, { traitName, fields });\n        }\n    }\n\n    // Check each listener's payloadMapping references\n    for (const trait of traits) {\n        if (!trait.listens) continue;\n\n        for (const listener of trait.listens) {\n            const emitter = emitIndex.get(listener.event);\n            if (!emitter) continue; // No emitter found — separate validation concern\n\n            if (!listener.payloadMapping) continue;\n\n            // Extract @payload.X references from payloadMapping values\n            const payloadRefs = extractPayloadReferences(listener.payloadMapping);\n\n            for (const ref of payloadRefs) {\n                if (!emitter.fields.includes(ref)) {\n                    mismatches.push({\n                        listenerTrait: trait.name,\n                        emitterTrait: emitter.traitName,\n                        event: listener.event,\n                        referencedField: ref,\n                        availableFields: emitter.fields,\n                    });\n                }\n            }\n        }\n    }\n\n    return mismatches;\n}\n\n/**\n * Extract payload field references from a payloadMapping object.\n * Finds all `@payload.fieldName` patterns and returns the field names.\n */\nfunction extractPayloadReferences(mapping: EventPayload): string[] {\n    const refs: string[] = [];\n\n    function collect(value: unknown): void {\n        if (typeof value === 'string') {\n            const match = value.match(/^@payload\\.(\\w+)$/);\n            if (match) {\n                refs.push(match[1]);\n            }\n        } else if (typeof value === 'object' && value !== null) {\n            if (Array.isArray(value)) {\n                value.forEach(collect);\n            } else {\n                Object.values(value as EventPayload).forEach(collect);\n            }\n        }\n    }\n\n    Object.values(mapping).forEach(collect);\n    return [...new Set(refs)];\n}\n\n/**\n * Build emit declarations map from trait definitions.\n * Extracts emits from transitions that use the `emit` effect.\n *\n * Note: This is a heuristic — it parses emit effects from transitions.\n * For full accuracy, the schema should include explicit `emits` declarations.\n */\nexport function buildEmitsFromTraits(\n    traits: TraitDefinition[],\n    explicitEmits?: Map<string, EmitDeclaration[]>\n): Map<string, EmitDeclaration[]> {\n    // Start with explicit emits if provided\n    const result = new Map<string, EmitDeclaration[]>(explicitEmits ?? []);\n\n    for (const trait of traits) {\n        if (result.has(trait.name)) continue; // Explicit declarations take precedence\n\n        const emitDecls: EmitDeclaration[] = [];\n        for (const transition of trait.transitions) {\n            if (!transition.effects) continue;\n\n            for (const effect of transition.effects) {\n                if (!Array.isArray(effect)) continue;\n                if (effect[0] === 'emit' && typeof effect[1] === 'string') {\n                    const event = effect[1] as string;\n                    // Payload is in effect[2] if present\n                    const payloadObj = effect[2] as EventPayload | undefined;\n                    const payload = payloadObj\n                        ? Object.keys(payloadObj).map((name) => ({ name }))\n                        : undefined;\n\n                    // Avoid duplicates\n                    if (!emitDecls.some((d) => d.event === event)) {\n                        emitDecls.push({ event, payload });\n                    }\n                }\n            }\n        }\n\n        if (emitDecls.length > 0) {\n            result.set(trait.name, emitDecls);\n        }\n    }\n\n    return result;\n}\n"]}

package/dist/{types-BrbvZxzX.d.ts → types-DYcUvi4H.d.ts}

@@ -1,3 +1,5 @@
+import { EventPayload, EntityRow, ServiceParams, ResolvedPatternProps } from '@almadar/core';
+
 /**
  * Unified Runtime Types
  *
@@ -5,6 +7,13 @@
  *
  * @packageDocumentation
  */
+
+/** Alias for ResolvedPatternProps to avoid breaking internal consumers */
+type PatternProps = ResolvedPatternProps;
+/** Configuration context */
+type ConfigContext = {
+    [key: string]: string | number | boolean | null | undefined;
+};
 /**
  * Event structure for cross-trait communication
  */
@@ -12,7 +21,7 @@ interface RuntimeEvent {
     /** Event type (e.g., "ORDER_CONFIRMED", "TraitName.EVENT_NAME") */
     type: string;
     /** Event payload data */
-    payload?: Record<string, unknown>;
+    payload?: EventPayload;
     /** Timestamp when event was emitted */
     timestamp: number;
     /** Source information for debugging */
@@ -30,7 +39,7 @@ type Unsubscribe = () => void;
  */
 interface IEventBus {
     /** Emit an event */
-    emit(type: string, payload?: Record<string, unknown>, source?: RuntimeEvent['source']): void;
+    emit(type: string, payload?: EventPayload, source?: RuntimeEvent['source']): void;
     /** Subscribe to an event */
     on(type: string, listener: EventListener): Unsubscribe;
     /** Subscribe to ALL events (wildcard listener) */
@@ -55,7 +64,7 @@ interface TraitState {
     /** Last event that caused a transition */
     lastEvent: string | null;
     /** Custom context data */
-    context: Record<string, unknown>;
+    context: ConfigContext;
 }
 /**
  * Result of processing an event through a state machine
@@ -103,7 +112,7 @@ interface TraitDefinition {
     listens?: Array<{
         event: string;
         triggers: string;
-        payloadMapping?: Record<string, unknown>;
+        payloadMapping?: EventPayload;
     }>;
 }
 /**
@@ -114,13 +123,13 @@ interface TraitDefinition {
  */
 interface EffectHandlers {
     /** Emit an event to the event bus */
-    emit: (event: string, payload?: Record<string, unknown>) => void;
+    emit: (event: string, payload?: EventPayload) => void;
     /** Persist data (create/update/delete/batch) */
-    persist: (action: 'create' | 'update' | 'delete' | 'batch', entityType: string, data?: Record<string, unknown>) => Promise<void>;
+    persist: (action: 'create' | 'update' | 'delete' | 'batch', entityType: string, data?: EntityRow) => Promise<void>;
     /** Set a field value on an entity */
     set: (entityId: string, field: string, value: unknown) => void;
     /** Call an external service */
-    callService: (service: string, action: string, params?: Record<string, unknown>) => Promise<unknown>;
+    callService: (service: string, action: string, params?: ServiceParams) => Promise<unknown>;
     /** Fetch entity data (server only) - returns data for client-side rendering */
     fetch?: (entityType: string, options?: {
         id?: string;
@@ -129,15 +138,17 @@ interface EffectHandlers {
         offset?: number;
         /** Relation fields to include (populate) in the response */
         include?: string[];
-    }) => Promise<Record<string, unknown> | Record<string, unknown>[] | null>;
+    }) => Promise<EntityRow | EntityRow[] | null>;
     /** Spawn a new entity instance */
-    spawn?: (entityType: string, props?: Record<string, unknown>) => void;
+    spawn?: (entityType: string, props?: EntityRow) => void;
     /** Despawn (delete) an entity instance */
     despawn?: (entityId: string) => void;
     /** Render UI to a slot (client only) */
-    renderUI?: (slot: string, pattern: unknown, props?: Record<string, unknown>, priority?: number) => void;
+    renderUI?: (slot: string, pattern: unknown, props?: PatternProps, priority?: number) => void;
     /** Navigate to a route (client only) */
-    navigate?: (path: string, params?: Record<string, unknown>) => void;
+    navigate?: (path: string, params?: {
+        [key: string]: string;
+    }) => void;
     /** Show a notification (client: toast, server: log) */
     notify?: (message: string, type: 'success' | 'error' | 'warning' | 'info') => void;
     /** Log a message */
@@ -149,20 +160,27 @@ interface EffectHandlers {
         limit?: number;
         offset?: number;
         include?: string[];
-    }) => Promise<Record<string, unknown> | Record<string, unknown>[] | null>;
+    }) => Promise<EntityRow | EntityRow[] | null>;
     /** Deref: one-shot data read (server: same as fetch) */
     deref?: (entityType: string, options?: {
         id?: string;
         filter?: unknown;
-    }) => Promise<Record<string, unknown> | Record<string, unknown>[] | null>;
+    }) => Promise<EntityRow | EntityRow[] | null>;
     /** Swap!: atomic read-modify-write on an entity */
-    swap?: (entityType: string, entityId: string, transform: unknown) => Promise<Record<string, unknown> | null>;
+    swap?: (entityType: string, entityId: string, transform: unknown) => Promise<EntityRow | null>;
     /** Watch: client-side reactive subscription (no-op on server) */
-    watch?: (entityType: string, options?: Record<string, unknown>) => void;
+    watch?: (entityType: string, options?: {
+        id?: string;
+        filter?: unknown;
+        limit?: number;
+    }) => void;
     /** Atomic: execute inner effects as a transaction */
     atomic?: (effects: unknown[]) => Promise<void>;
     /** Watch file system for changes matching glob pattern */
-    osWatchFiles?: (glob: string, options: Record<string, unknown>) => void;
+    osWatchFiles?: (glob: string, options: {
+        recursive?: boolean;
+        debounce?: number;
+    }) => void;
     /** Monitor a process by name */
     osWatchProcess?: (name: string, subcommand?: string) => void;
     /** Monitor a port for open/close */
@@ -183,13 +201,13 @@ interface EffectHandlers {
  */
 interface BindingContext {
     /** Current entity data */
-    entity?: Record<string, unknown>;
+    entity?: EntityRow;
     /** Event payload data */
-    payload?: Record<string, unknown>;
+    payload?: EventPayload;
     /** Current state name */
     state?: string;
     /** Trait-level state/config */
-    config?: Record<string, unknown>;
+    config?: ConfigContext;
     /** Additional custom bindings */
     [key: string]: unknown;
 }
@@ -293,4 +311,4 @@ interface TransitionObserver {
  */
 declare const HANDLER_MANIFEST: Record<ExecutionEnvironment, string[]>;
 
-export { type BindingContext as B, type EffectHandlers as E, HANDLER_MANIFEST as H, type IEventBus as I, type RuntimeConfig as R, type TraitState as T, type Unsubscribe as U, type TraitDefinition as a, type TransitionObserver as b, type TransitionResult as c, type EffectContext as d, type ExecutionEnvironment as e, type EffectResult as f, type Effect as g, type EventListener as h, type RuntimeEvent as i };
+export { type BindingContext as B, type EffectHandlers as E, HANDLER_MANIFEST as H, type IEventBus as I, type PatternProps as P, type RuntimeConfig as R, type TraitDefinition as T, type Unsubscribe as U, type EffectContext as a, type ExecutionEnvironment as b, type EffectResult as c, type Effect as d, type EventListener as e, type RuntimeEvent as f, type TraitState as g, type TransitionObserver as h, type TransitionResult as i };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/runtime",
-  "version": "2.5.0",
+  "version": "2.6.1",
   "description": "Interpreted runtime for Almadar orbital applications (OrbitalServerRuntime)",
   "type": "module",
   "main": "./dist/index.js",
@@ -38,7 +38,7 @@
   "dependencies": {
     "@almadar/evaluator": ">=2.5.4",
     "@almadar/operators": ">=2.1.3",
-    "@almadar/core": ">=2.6.3",
+    "@almadar/core": ">=2.13.0",
     "@faker-js/faker": "^9.3.0"
   },
   "peerDependencies": {
@@ -53,7 +53,7 @@
     "vitest": "^2.1.0",
     "eslint": "10.0.0",
     "@typescript-eslint/parser": "8.56.0",
-    "@almadar/eslint-plugin": ">=2.3.0"
+    "@almadar/eslint-plugin": ">=2.7.0"
   },
   "repository": {
     "type": "git",