@almadar/runtime 4.10.2 → 4.11.1

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { B as BindingContext, E as EvaluationContextExtensions, P as PatternProps, a as EffectHandlers, b as EffectContext, c as ExecutionEnvironment, d as EffectResult, T as TraitDefinition } from './types-DwDhc9Jt.js';
 export { e as Effect, f as EventListener, H as HANDLER_MANIFEST, I as IEventBus, R as RuntimeConfig, g as RuntimeEvent, h as TraitState, i as TransitionObserver, j as TransitionResult, U as Unsubscribe } from './types-DwDhc9Jt.js';
-import { U as UnifiedLoaderOptions, S as SchemaLoader, I as ImportChainLike, L as LoadResult, a as LoadedSchema, b as LoadedOrbital } from './OrbitalServerRuntime-B5lfym6T.js';
-export { E as EntitySharingMap, c as EventBus, d as EventNamespaceMap, O as OrbitalEventRequest, e as OrbitalEventResponse, f as OrbitalServerRuntimeConfig, P as PersistenceAdapter, g as PreprocessOptions, h as PreprocessResult, i as PreprocessedSchema, j as ProcessEventOptions, R as RegisteredOrbital, k as RuntimeOrbital, l as RuntimeOrbitalSchema, m as RuntimeTrait, n as StateMachineManager, o as createInitialTraitState, p as findInitialState, q as findTransition, r as getIsolatedCollectionName, s as getNamespacedEvent, t as isBrowser, u as isElectron, v as isNamespacedEvent, w as isNode, x as normalizeEventKey, y as parseNamespacedEvent, z as preprocessSchema, A as processEvent } from './OrbitalServerRuntime-B5lfym6T.js';
+import { U as UnifiedLoaderOptions, S as SchemaLoader, I as ImportChainLike, L as LoadResult, a as LoadedSchema, b as LoadedOrbital, P as PersistenceAdapter } from './OrbitalServerRuntime-D-b_dg8I.js';
+export { E as EntitySharingMap, c as EventBus, d as EventNamespaceMap, e as InMemoryPersistence, O as OrbitalEventRequest, f as OrbitalEventResponse, g as OrbitalServerRuntimeConfig, h as PreprocessOptions, i as PreprocessResult, j as PreprocessedSchema, k as ProcessEventOptions, R as RegisteredOrbital, l as RuntimeOrbital, m as RuntimeOrbitalSchema, n as RuntimeTrait, o as StateMachineManager, p as createInitialTraitState, q as findInitialState, r as findTransition, s as getIsolatedCollectionName, t as getNamespacedEvent, u as isBrowser, v as isElectron, w as isNamespacedEvent, x as isNode, y as normalizeEventKey, z as parseNamespacedEvent, A as preprocessSchema, B as processEvent } from './OrbitalServerRuntime-D-b_dg8I.js';
 import { EvaluationContext } from '@almadar/evaluator';
 export { EvaluationContext, createMinimalContext } from '@almadar/evaluator';
 import { EventPayload, EntityRow, OrbitalDefinition, OrbitalSchema } from '@almadar/core';
@@ -370,29 +370,6 @@ interface CreateClientEffectHandlersOptions {
  */
 declare function createClientEffectHandlers(options: CreateClientEffectHandlersOptions): EffectHandlers;
 
-/**
- * OS Trigger Handlers — Server-Side Only
- *
- * Provides Node.js implementations for all 8 os/* operators.
- * Used by OrbitalServerRuntime (interpreted path).
- *
- * NOT exported from the main index.ts because it imports Node.js-only modules.
- * Import directly: import { createOsHandlers } from '@almadar/runtime/createOsHandlers';
- *
- * @packageDocumentation
- */
-
-interface OsHandlerContext {
-    /** Emit an event on the EventBus */
-    emitEvent: (type: string, payload: EventPayload) => void;
-    /** Working directory for file watching (defaults to process.cwd()) */
-    cwd?: string;
-}
-interface OsHandlerResult {
-    handlers: Partial<EffectHandlers>;
-    cleanup: () => void;
-}
-
 /**
  * MockPersistenceAdapter - In-memory data store with faker-based mock generation
  *
@@ -425,6 +402,208 @@ interface MockPersistenceConfig {
     /** Enable debug logging */
     debug?: boolean;
 }
+/**
+ * In-memory mock data store with CRUD operations and faker-based seeding.
+ */
+declare class MockPersistenceAdapter implements PersistenceAdapter {
+    private stores;
+    private schemas;
+    private idCounters;
+    private config;
+    constructor(config?: MockPersistenceConfig);
+    private getStore;
+    private nextId;
+    /**
+     * Register an entity schema and seed mock data.
+     * If the schema has seedData, those instances are used directly.
+     * Otherwise, random mock data is generated with faker.
+     */
+    registerEntity(schema: EntitySchema, seedCount?: number): void;
+    /**
+     * Seed an entity with pre-authored instance data.
+     */
+    seedFromInstances(entityName: string, instances: EntityRow[]): void;
+    /**
+     * Seed an entity with mock data.
+     */
+    seed(entityName: string, fields: EntityField[], count: number): void;
+    /**
+     * Generate a single mock item based on field schemas.
+     */
+    private generateMockItem;
+    /**
+     * Generate a mock value for a field based on its schema.
+     */
+    private generateFieldValue;
+    /**
+     * Generate a string value based on the field's declared schema metadata.
+     * Reads `values` (enum) first, then `format` (email/url/phone/uuid/date/
+     * datetime), then falls back to faker.lorem.words. No field-name heuristics
+     * — the schema is the source of truth. If a caller needs a real email, they
+     * declare `format: "email"`; if they need an enum, they declare `values: [...]`.
+     */
+    private generateStringValue;
+    /**
+     * Generate a date value. Uses the field's `format` (date vs datetime) to
+     * decide ISO shape; otherwise returns a recent ISO-8601 datetime. No
+     * field-name heuristics.
+     */
+    private generateDateValue;
+    private capitalizeFirst;
+    create(entityType: string, data: EntityRow): Promise<{
+        id: string;
+    }>;
+    /**
+     * Fill in any entity-declared field defaults that the caller omitted.
+     * SAVE payloads coming from form-section only carry the fields the user
+     * edited; persisted rows should still honor `field.default` so downstream
+     * row-content probes (VG11f) see a row whose every declared-default field
+     * is non-empty. `@now` resolves to the current ISO timestamp.
+     */
+    private applyFieldDefaults;
+    update(entityType: string, id: string, data: EntityRow): Promise<void>;
+    delete(entityType: string, id: string): Promise<void>;
+    getById(entityType: string, id: string): Promise<EntityRow | null>;
+    list(entityType: string): Promise<Array<EntityRow>>;
+    /**
+     * Clear all data for an entity.
+     */
+    clear(entityName: string): void;
+    /**
+     * Clear all data.
+     */
+    clearAll(): void;
+    /**
+     * Get count of items for an entity.
+     */
+    count(entityName: string): number;
+}
+/**
+ * Create a MockPersistenceAdapter instance.
+ */
+declare function createMockPersistence(config?: MockPersistenceConfig): MockPersistenceAdapter;
+
+/**
+ * ServerEffectHandlers — reusable factory for the server-side effect layer.
+ *
+ * Mirrors the handlers built inline in
+ * `OrbitalServerRuntime.executeEffects` so both the real server runtime
+ * AND the in-browser mock runtime (`@almadar/ui` OrbPreview autoMock) can
+ * share the same `fetch` / `persist` / `set` / `ref` / `deref` / `swap!` /
+ * `atomic` / `callService` semantics against a `PersistenceAdapter`.
+ *
+ * Browser-safe: only imports core + this package's browser-safe modules.
+ * Does NOT import express/Node, so it is reachable from `@almadar/ui`.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Minimal event-bus contract the server handlers need. Narrower than the
+ * full `IEventBus` so clients with a React-context bus (only `emit` is
+ * relevant for effect dispatch) can hand it in without adapter code.
+ */
+interface ServerEffectEventBus {
+    emit(event: string, payload?: EventPayload, source?: {
+        orbital?: string;
+        trait?: string;
+    }): void;
+}
+/**
+ * Result entry recorded for each effect invocation. Mirrors the server
+ * runtime's `EffectResult`. Callers who want telemetry pass an array that
+ * the factory appends to; otherwise it's unused.
+ */
+interface ServerEffectResult {
+    effect: "set" | "persist" | "call-service" | "fetch" | "ref" | "deref" | "swap" | "atomic";
+    action?: string;
+    entityType?: string;
+    data?: unknown;
+    success: boolean;
+    error?: string;
+}
+interface CreateServerEffectHandlersOptions {
+    /** Persistent store backing `fetch` / `persist` / `ref` / `deref` / `swap`. */
+    persistence: PersistenceAdapter;
+    /** Event bus that `emit` delegates to. Only `.emit()` is required. */
+    eventBus: ServerEffectEventBus;
+    /** The trait's linked entity type (used as the default for persist/set). */
+    entityType: string;
+    /** Current entity row id (used by `set`, `persist update/delete` fallback). */
+    entityId?: string;
+    /**
+     * Binding object passed to inner `atomic` evaluator. When absent, atomic
+     * effects still run but have no access to `@entity` / `@payload` bindings.
+     */
+    bindings?: BindingContext;
+    /** Effect context passed to the inner `atomic` executor. */
+    context?: EffectContext;
+    /** Per-event result sink. Optional — telemetry only. */
+    effectResults?: ServerEffectResult[];
+    /**
+     * Per-event fetched-data cache. `fetch` writes here so downstream UI
+     * renderers can resolve `@entity` bindings from the latest load without
+     * a separate round-trip.
+     */
+    fetchedData?: Record<string, EntityRow[]>;
+    /** Per-event emit log. Optional — telemetry only. */
+    emittedEvents?: Array<{
+        event: string;
+        payload?: EventPayload;
+    }>;
+    /** Source stamp applied to all emits. */
+    source?: {
+        orbital?: string;
+        trait?: string;
+    };
+    /** Consumer-supplied `call-service` handler. When absent, calls warn and return null. */
+    callService?: (service: string, action: string, params: unknown) => Promise<unknown>;
+    /** Verbose logging. */
+    debug?: boolean;
+}
+/**
+ * Build the full server-side effect handler set bound to a persistence
+ * adapter. The returned object satisfies `EffectHandlers` and can be
+ * handed directly to `EffectExecutor`.
+ *
+ * Scope: one handler object per transition — capture `entityId`,
+ * `bindings`, `context`, and the sink arrays at build time. For a new
+ * transition, call this factory again.
+ *
+ * Intentionally does NOT implement:
+ * - `renderUI` / `notify` / `navigate` — these are client-side, provided
+ *   by `createClientEffectHandlers`. A mock runtime merges both handler
+ *   sets.
+ * - `os/watch-*` observers — these are a no-op outside the server.
+ * - Schema-aware relation cardinality / on-delete cascades — those live
+ *   in `OrbitalServerRuntime` and depend on the full registered schema.
+ *   Clients that need them can wrap the persist handler with their own
+ *   validation.
+ */
+declare function createServerEffectHandlers(opts: CreateServerEffectHandlersOptions): EffectHandlers;
+
+/**
+ * OS Trigger Handlers — Server-Side Only
+ *
+ * Provides Node.js implementations for all 8 os/* operators.
+ * Used by OrbitalServerRuntime (interpreted path).
+ *
+ * NOT exported from the main index.ts because it imports Node.js-only modules.
+ * Import directly: import { createOsHandlers } from '@almadar/runtime/createOsHandlers';
+ *
+ * @packageDocumentation
+ */
+
+interface OsHandlerContext {
+    /** Emit an event on the EventBus */
+    emitEvent: (type: string, payload: EventPayload) => void;
+    /** Working directory for file watching (defaults to process.cwd()) */
+    cwd?: string;
+}
+interface OsHandlerResult {
+    handlers: Partial<EffectHandlers>;
+    cleanup: () => void;
+}
 
 /**
  * PayloadValidator - Cross-Trait Payload Shape Validation (RCG-10)
@@ -659,4 +838,4 @@ declare namespace index {
   export { type index_ComposeBehaviorsInput as ComposeBehaviorsInput, type index_ComposeBehaviorsResult as ComposeBehaviorsResult, type index_EventWiringEntry as EventWiringEntry, type index_LayoutStrategy as LayoutStrategy, type index_PipeStep as PipeStep, index_applyEventWiring as applyEventWiring, index_composeBehaviors as composeBehaviors, index_detectLayoutStrategy as detectLayoutStrategy, index_pipeBehaviors as pipeBehaviors };
 }
 
-export { BindingContext, type ClientEventBus, type ComposeBehaviorsInput, type ComposeBehaviorsResult, type CreateClientEffectHandlersOptions, EffectContext, EffectExecutor, type EffectExecutorOptions, EffectHandlers, EffectResult, type EntityField, type EntitySchema, type EventWiringEntry, ExecutionEnvironment, ImportChainLike, type LayoutStrategy, LoadResult, LoadedOrbital, LoadedSchema, type MockPersistenceConfig, type OsHandlerContext, type OsHandlerResult, type PayloadMismatch, type PipeStep, SchemaLoader, type SlotSetter, TraitDefinition, UnifiedLoaderOptions, applyEventWiring, buildEmitsFromTraits, composeBehaviors, index as composition, containsBindings, createClientEffectHandlers, createContextFromBindings, createTestExecutor, createUnifiedLoader, detectLayoutStrategy, extractBindings, interpolateProps, interpolateValue, pipeBehaviors, validatePayloadShapes };
+export { BindingContext, type ClientEventBus, type ComposeBehaviorsInput, type ComposeBehaviorsResult, type CreateClientEffectHandlersOptions, type CreateServerEffectHandlersOptions, EffectContext, EffectExecutor, type EffectExecutorOptions, EffectHandlers, EffectResult, type EntityField, type EntitySchema, type EventWiringEntry, ExecutionEnvironment, ImportChainLike, type LayoutStrategy, LoadResult, LoadedOrbital, LoadedSchema, MockPersistenceAdapter, type MockPersistenceConfig, type OsHandlerContext, type OsHandlerResult, type PayloadMismatch, PersistenceAdapter, type PipeStep, SchemaLoader, type ServerEffectResult, type SlotSetter, TraitDefinition, UnifiedLoaderOptions, applyEventWiring, buildEmitsFromTraits, composeBehaviors, index as composition, containsBindings, createClientEffectHandlers, createContextFromBindings, createMockPersistence, createServerEffectHandlers, createTestExecutor, createUnifiedLoader, detectLayoutStrategy, extractBindings, interpolateProps, interpolateValue, pipeBehaviors, validatePayloadShapes };

package/dist/index.js

@@ -1,5 +1,7 @@
-export { EffectExecutor, EventBus, HANDLER_MANIFEST, StateMachineManager, containsBindings, createContextFromBindings, createInitialTraitState, createMinimalContext, createTestExecutor, createUnifiedLoader, extractBindings, findInitialState, findTransition, getIsolatedCollectionName, getNamespacedEvent, interpolateProps, interpolateValue, isBrowser, isElectron, isNamespacedEvent, isNode, normalizeEventKey, parseNamespacedEvent, preprocessSchema, processEvent } from './chunk-K36736GF.js';
+import { EffectExecutor, createContextFromBindings } from './chunk-RCWMQH7Y.js';
+export { EffectExecutor, EventBus, HANDLER_MANIFEST, InMemoryPersistence, MockPersistenceAdapter, StateMachineManager, containsBindings, createContextFromBindings, createInitialTraitState, createMinimalContext, createMockPersistence, createTestExecutor, createUnifiedLoader, extractBindings, findInitialState, findTransition, getIsolatedCollectionName, getNamespacedEvent, interpolateProps, interpolateValue, isBrowser, isElectron, isNamespacedEvent, isNode, normalizeEventKey, parseNamespacedEvent, preprocessSchema, processEvent } from './chunk-RCWMQH7Y.js';
 import { __export } from './chunk-PZ5AY32C.js';
+import { evaluate } from '@almadar/evaluator';
 import { isInlineTrait } from '@almadar/core';
 
 // src/ClientEffectHandlers.ts
@@ -35,6 +37,392 @@ function createClientEffectHandlers(options) {
     })
   };
 }
+function createServerEffectHandlers(opts) {
+  const {
+    persistence,
+    eventBus,
+    entityType,
+    entityId,
+    bindings,
+    context,
+    effectResults,
+    fetchedData,
+    emittedEvents,
+    source,
+    callService: consumerCallService,
+    debug
+  } = opts;
+  const record = (entry) => {
+    effectResults?.push(entry);
+  };
+  const handlers = {
+    emit: (event, eventPayload, emitSource) => {
+      if (debug) {
+        console.log(`[ServerEffectHandlers] emit ${event}`, eventPayload);
+      }
+      const stamp = emitSource ?? source;
+      eventBus.emit(event, eventPayload, stamp);
+      emittedEvents?.push({ event, payload: eventPayload });
+    },
+    set: async (targetId, field, value) => {
+      const id = targetId || entityId;
+      if (!id) return;
+      try {
+        await persistence.update(entityType, id, { [field]: value });
+        record({
+          effect: "set",
+          entityType,
+          data: { id, field, value },
+          success: true
+        });
+      } catch (err) {
+        record({
+          effect: "set",
+          entityType,
+          data: { id, field, value },
+          success: false,
+          error: err instanceof Error ? err.message : String(err)
+        });
+      }
+    },
+    persist: async (action, targetEntityType, data) => {
+      if (action === "batch") {
+        const operations = data?.operations;
+        if (!Array.isArray(operations) || operations.length === 0) {
+          record({
+            effect: "persist",
+            action: "batch",
+            success: false,
+            error: "Batch requires a non-empty operations array"
+          });
+          return;
+        }
+        const batchResults = [];
+        const completed = [];
+        let batchFailed = false;
+        let batchError = "";
+        for (const op of operations) {
+          if (!Array.isArray(op) || op.length < 2) {
+            batchFailed = true;
+            batchError = `Invalid batch operation format: ${JSON.stringify(op)}`;
+            break;
+          }
+          const [opAction, opEntityType, ...opRest] = op;
+          try {
+            switch (opAction) {
+              case "create": {
+                const createData = opRest[0] || {};
+                const { id: newId } = await persistence.create(
+                  opEntityType,
+                  createData
+                );
+                batchResults.push({
+                  action: "create",
+                  entityType: opEntityType,
+                  id: newId,
+                  ...createData
+                });
+                completed.push({
+                  action: "create",
+                  entityType: opEntityType,
+                  id: newId
+                });
+                break;
+              }
+              case "update": {
+                const updateId = opRest[0];
+                const updateData = opRest[1] || {};
+                await persistence.update(opEntityType, updateId, updateData);
+                const updated = await persistence.getById(opEntityType, updateId);
+                batchResults.push({
+                  action: "update",
+                  entityType: opEntityType,
+                  id: updateId,
+                  ...updated || updateData
+                });
+                completed.push({
+                  action: "update",
+                  entityType: opEntityType,
+                  id: updateId
+                });
+                break;
+              }
+              case "delete": {
+                const deleteId = opRest[0];
+                await persistence.delete(opEntityType, deleteId);
+                batchResults.push({
+                  action: "delete",
+                  entityType: opEntityType,
+                  id: deleteId,
+                  deleted: true
+                });
+                completed.push({
+                  action: "delete",
+                  entityType: opEntityType,
+                  id: deleteId
+                });
+                break;
+              }
+              default:
+                batchFailed = true;
+                batchError = `Unknown batch operation action: ${opAction}`;
+                break;
+            }
+          } catch (err) {
+            batchFailed = true;
+            batchError = `Batch operation [${opAction}, ${opEntityType}] failed: ${err instanceof Error ? err.message : String(err)}`;
+            break;
+          }
+          if (batchFailed) break;
+        }
+        record({
+          effect: "persist",
+          action: "batch",
+          data: {
+            operations: batchResults,
+            completedCount: completed.length,
+            totalCount: operations.length
+          },
+          success: !batchFailed,
+          ...batchFailed ? { error: batchError } : {}
+        });
+        return;
+      }
+      const type = targetEntityType || entityType;
+      let resultData;
+      try {
+        switch (action) {
+          case "create": {
+            const { id } = await persistence.create(type, data ?? {});
+            resultData = { id, ...data ?? {} };
+            break;
+          }
+          case "update": {
+            const row = data ?? {};
+            const idOrFallback = row.id ?? entityId;
+            if (idOrFallback) {
+              await persistence.update(type, idOrFallback, row);
+              const updated = await persistence.getById(type, idOrFallback);
+              resultData = updated ?? { id: idOrFallback, ...row };
+            }
+            break;
+          }
+          case "delete": {
+            const directId = typeof data === "string" ? data : void 0;
+            const nestedId = typeof data === "object" && data !== null ? data.id : void 0;
+            const deleteId = directId ?? nestedId ?? entityId;
+            if (deleteId) {
+              await persistence.delete(type, deleteId);
+              resultData = { id: deleteId, deleted: true };
+            }
+            break;
+          }
+        }
+        record({
+          effect: "persist",
+          action,
+          entityType: type,
+          data: resultData,
+          success: true
+        });
+      } catch (err) {
+        record({
+          effect: "persist",
+          action,
+          entityType: type,
+          success: false,
+          error: err instanceof Error ? err.message : String(err)
+        });
+      }
+    },
+    callService: async (service, action, params) => {
+      try {
+        let result = null;
+        if (consumerCallService) {
+          result = await consumerCallService(service, action, params);
+        } else if (debug) {
+          console.warn(
+            `[ServerEffectHandlers] call-service not configured: ${service}.${action}`
+          );
+        }
+        record({
+          effect: "call-service",
+          action: `${service}.${action}`,
+          data: result,
+          success: true
+        });
+        return result;
+      } catch (err) {
+        record({
+          effect: "call-service",
+          action: `${service}.${action}`,
+          success: false,
+          error: err instanceof Error ? err.message : String(err)
+        });
+        return null;
+      }
+    },
+    fetch: async (fetchEntityType, options) => {
+      try {
+        let result = null;
+        if (options?.id) {
+          const entity = await persistence.getById(fetchEntityType, options.id);
+          if (entity) {
+            if (fetchedData) fetchedData[fetchEntityType] = [entity];
+            result = entity;
+          }
+        } else {
+          let entities = await persistence.list(fetchEntityType);
+          if (options?.offset && options.offset > 0) {
+            entities = entities.slice(options.offset);
+          }
+          if (options?.limit && options.limit > 0) {
+            entities = entities.slice(0, options.limit);
+          }
+          if (fetchedData) fetchedData[fetchEntityType] = entities;
+          result = entities;
+        }
+        if (bindings && result) {
+          const records = Array.isArray(result) ? result : [result];
+          if (records.length > 0) {
+            const merged = Object.assign([...records], records[0]);
+            bindings[fetchEntityType] = merged;
+            if (fetchEntityType === entityType) {
+              bindings.entity = merged;
+            }
+          }
+        }
+        return result;
+      } catch (err) {
+        console.error(
+          `[ServerEffectHandlers] fetch error for ${fetchEntityType}:`,
+          err
+        );
+        return null;
+      }
+    },
+    ref: async (refEntityType, options) => {
+      return handlers.fetch(refEntityType, options);
+    },
+    deref: async (derefEntityType, options) => {
+      try {
+        let result = null;
+        if (options?.id) {
+          const entity = await persistence.getById(derefEntityType, options.id);
+          if (entity) {
+            if (fetchedData) fetchedData[derefEntityType] = [entity];
+            result = entity;
+          }
+        } else {
+          const entities = await persistence.list(derefEntityType);
+          if (fetchedData) fetchedData[derefEntityType] = entities;
+          result = entities;
+        }
+        if (bindings && result) {
+          const records = Array.isArray(result) ? result : [result];
+          if (records.length > 0) {
+            const merged = Object.assign([...records], records[0]);
+            bindings[derefEntityType] = merged;
+            if (derefEntityType === entityType) {
+              bindings.entity = merged;
+            }
+          }
+        }
+        record({
+          effect: "deref",
+          entityType: derefEntityType,
+          success: true
+        });
+        return result;
+      } catch (err) {
+        record({
+          effect: "deref",
+          entityType: derefEntityType,
+          success: false,
+          error: err instanceof Error ? err.message : String(err)
+        });
+        return null;
+      }
+    },
+    swap: async (swapEntityType, swapEntityId, transform) => {
+      try {
+        const current = await persistence.getById(swapEntityType, swapEntityId);
+        if (!current) {
+          record({
+            effect: "swap",
+            entityType: swapEntityType,
+            success: false,
+            error: `Entity ${swapEntityType}/${swapEntityId} not found`
+          });
+          return null;
+        }
+        const ctx = createContextFromBindings(
+          { current, entity: bindings?.entity, payload: bindings?.payload },
+          false
+        );
+        let newData;
+        if (Array.isArray(transform)) {
+          const evalResult = evaluate(transform, ctx);
+          if (evalResult && typeof evalResult === "object" && !Array.isArray(evalResult)) {
+            newData = evalResult;
+          } else {
+            newData = current;
+          }
+        } else if (typeof transform === "object" && transform !== null) {
+          newData = { ...current, ...transform };
+        } else {
+          record({
+            effect: "swap",
+            entityType: swapEntityType,
+            success: false,
+            error: "swap! transform must be an S-expression or object"
+          });
+          return null;
+        }
+        await persistence.update(swapEntityType, swapEntityId, newData);
+        record({
+          effect: "swap",
+          entityType: swapEntityType,
+          data: { id: swapEntityId, ...newData },
+          success: true
+        });
+        return newData;
+      } catch (err) {
+        record({
+          effect: "swap",
+          entityType: swapEntityType,
+          success: false,
+          error: err instanceof Error ? err.message : String(err)
+        });
+        return null;
+      }
+    },
+    watch: (_watchEntityType) => {
+    },
+    atomic: async (atomicEffects) => {
+      const atomicExecutor = new EffectExecutor({
+        handlers,
+        bindings: bindings ?? {},
+        context: context ?? {
+          traitName: "atomic",
+          state: "unknown",
+          transition: "unknown"
+        }
+      });
+      try {
+        await atomicExecutor.executeAll(atomicEffects);
+        record({ effect: "atomic", success: true });
+      } catch (err) {
+        record({
+          effect: "atomic",
+          success: false,
+          error: err instanceof Error ? err.message : String(err)
+        });
+      }
+    }
+  };
+  return handlers;
+}
 
 // src/PayloadValidator.ts
 function validatePayloadShapes(traits, emits) {
@@ -327,6 +715,6 @@ function pipeBehaviors(seed, ...steps) {
   return current;
 }
 
-export { applyEventWiring, buildEmitsFromTraits, composeBehaviors, composition_exports as composition, createClientEffectHandlers, detectLayoutStrategy, pipeBehaviors, validatePayloadShapes };
+export { applyEventWiring, buildEmitsFromTraits, composeBehaviors, composition_exports as composition, createClientEffectHandlers, createServerEffectHandlers, detectLayoutStrategy, pipeBehaviors, validatePayloadShapes };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map