@almadar/runtime 5.0.0 → 5.2.0

package/dist/ServerBridge.d.ts

@@ -1,4 +1,4 @@
-import { I as IEventBus } from './types-DwDhc9Jt.js';
+import { I as IEventBus } from './types-SmmabGZk.js';
 import { EventPayload } from '@almadar/core';
 
 /**

package/dist/{chunk-S5OLFFHT.js → chunk-OG2NHXES.js}

@@ -175,9 +175,8 @@ function createLogger(namespace) {
     error: (msg, data) => log("ERROR", msg, data)
   };
 }
-
-// src/BindingResolver.ts
 var bindLog = createLogger("almadar:runtime:bindings");
+var renderLog = createLogger("almadar:runtime:render-ui");
 var CLIENT_ONLY_BINDING_ROOTS = /* @__PURE__ */ new Set(["trait"]);
 function isClientOnlyBinding(value) {
   if (!value.startsWith("@")) return false;
@@ -188,10 +187,27 @@ function isClientOnlyBinding(value) {
 }
 function interpolateProps(props, ctx) {
   const result = {};
+  let anyChanged = false;
   for (const [key, value] of Object.entries(props)) {
-    result[key] = interpolateValue(value, ctx);
+    const interpolated = interpolateValue(value, ctx);
+    result[key] = interpolated;
+    if (interpolated !== value) anyChanged = true;
+  }
+  const entityBindingRaw = props["entity"];
+  const typeBindingRaw = props["type"];
+  if (typeof entityBindingRaw === "string") {
+    const resolvedEntity = result["entity"];
+    const resolvedRow = resolvedEntity !== null && typeof resolvedEntity === "object" && !Array.isArray(resolvedEntity) ? resolvedEntity : null;
+    const ctxRow = ctx.payload["row"];
+    renderLog.debug("interpolateProps:entity", {
+      patternType: typeof typeBindingRaw === "string" ? typeBindingRaw : void 0,
+      entityBinding: entityBindingRaw,
+      resolvedIsObject: resolvedRow !== null,
+      resolvedEqualsCtxRow: ctxRow !== void 0 && resolvedRow !== null && resolvedRow === ctxRow,
+      resolvedRowId: resolvedRow?.id
+    });
   }
-  return result;
+  return anyChanged ? result : props;
 }
 function interpolateValue(value, ctx) {
   if (value === null || value === void 0) {
@@ -237,12 +253,20 @@ function interpolateEmbeddedBindings(value, ctx) {
 }
 function interpolateArray(value, ctx) {
   if (value.length === 0) {
-    return [];
+    return value;
   }
   if (isSExpression(value)) {
     return evaluate(value, ctx);
   }
-  return value.map((item) => interpolateValue(item, ctx));
+  const mapped = [];
+  let anyChanged = false;
+  for (let i = 0; i < value.length; i++) {
+    const item = value[i];
+    const interpolated = interpolateValue(item, ctx);
+    mapped.push(interpolated);
+    if (interpolated !== item) anyChanged = true;
+  }
+  return anyChanged ? mapped : value;
 }
 function isSExpression(value) {
   if (value.length === 0) return false;
@@ -343,6 +367,7 @@ function processEvent(options) {
     eventKey,
     payload,
     entityData,
+    config,
     guardMode = "permissive",
     strictBindings = false,
     contextExtensions
@@ -377,7 +402,13 @@ function processEvent(options) {
     const ctx = createContextFromBindings({
       entity: entityData,
       payload,
-      state: traitState.currentState
+      state: traitState.currentState,
+      // Surface call-site config so `@config.X` resolves inside
+      // guard expressions (matches the validator's allowed sigil
+      // list as of v3.12.0). createContextFromBindings already
+      // propagates `bindings.config` to ctx.config when present —
+      // we just need to pass it through here.
+      config
     }, strictBindings, contextExtensions);
     try {
       const guardPasses = evaluateGuard(
@@ -457,6 +488,15 @@ function compositeKey(traitName, scope) {
 }
 var StateMachineManager = class {
   traits = /* @__PURE__ */ new Map();
+  /**
+   * Per-trait call-site config, surfaced to guard expressions so
+   * `@config.X` resolves at runtime. Populated by the orbital's
+   * registration step (see `OrbitalServerRuntime.registerOrbital`'s
+   * `configByTrait` projection). Empty for atom-scope traits whose
+   * call-site config wasn't supplied — guards that read `@config.X`
+   * in that case will see `undefined` and short-circuit accordingly.
+   */
+  traitConfigs = /* @__PURE__ */ new Map();
   /**
    * State map keyed by `${traitName}::${entityId | __singleton__}`.
    *
@@ -499,6 +539,19 @@ var StateMachineManager = class {
   addTrait(trait) {
     this.traits.set(trait.name, trait);
   }
+  /**
+   * Bind the call-site config for a trait so guard `@config.X`
+   * resolves at runtime. Typically called by the orbital
+   * registration step right after `addTrait`. Idempotent; passing
+   * `undefined` clears the binding.
+   */
+  setTraitConfig(traitName, config) {
+    if (config === void 0) {
+      this.traitConfigs.delete(traitName);
+    } else {
+      this.traitConfigs.set(traitName, config);
+    }
+  }
   /**
    * Remove a trait from the manager.
    */
@@ -614,6 +667,7 @@ var StateMachineManager = class {
         eventKey,
         payload,
         entityData,
+        config: this.traitConfigs.get(traitName),
         guardMode: this.config.guardMode,
         strictBindings: this.config.strictBindings,
         contextExtensions: this.config.contextExtensions
@@ -683,6 +737,7 @@ var StateMachineManager = class {
         eventKey: entry.eventKey,
         payload: entry.payload,
         entityData: entry.entityData,
+        config: this.traitConfigs.get(traitName),
         guardMode: this.config.guardMode,
         strictBindings: this.config.strictBindings,
         contextExtensions: this.config.contextExtensions
@@ -1108,18 +1163,51 @@ var EffectExecutor = class {
         const action = args[0];
         const last = args[args.length - 1];
         const emitCfg = last && typeof last === "object" && !Array.isArray(last) && "emit" in last ? this.extractEmitConfig(last) : void 0;
+        effectLog.debug("persist:dispatch", {
+          action,
+          argCount: args.length,
+          argTypes: args.map((a) => Array.isArray(a) ? "array" : a === null ? "null" : typeof a).join(","),
+          traitName: this.context.traitName,
+          transition: this.context.transition
+        });
+        effectLog.debug("persist:emit-config", {
+          action,
+          hasEmitCfg: emitCfg !== void 0,
+          success: emitCfg?.success,
+          failure: emitCfg?.failure
+        });
         try {
           if (action === "batch") {
             const operations = args[1];
             await this.handlers.persist("batch", "", { operations });
+            effectLog.debug("persist:success", {
+              action,
+              entityType: "batch",
+              opCount: operations.length,
+              willEmit: emitCfg?.success
+            });
             this.emitSuccess(emitCfg, "success", operations);
+            effectLog.debug("persist:emit-fired", { action, eventName: emitCfg?.success });
           } else {
             const entityType = args[1];
             const data = args[2];
             await this.handlers.persist(action, entityType, data);
+            const dataId = typeof data === "string" ? data : data && typeof data === "object" ? data.id : void 0;
+            effectLog.debug("persist:success", {
+              action,
+              entityType,
+              dataId,
+              willEmit: emitCfg?.success
+            });
             this.emitSuccess(emitCfg, "success", data);
+            effectLog.debug("persist:emit-fired", { action, eventName: emitCfg?.success });
           }
         } catch (err) {
+          effectLog.error("persist:error", {
+            action,
+            entityType: action === "batch" ? "batch" : args[1],
+            error: err instanceof Error ? err.message : String(err)
+          });
           this.emitFailure(emitCfg, err);
           throw err;
         }
@@ -1482,6 +1570,106 @@ function createTestExecutor(overrides = {}) {
     debug: true
   });
 }
+
+// src/PayloadValidator.ts
+function validateEventPayload(eventKey, payload, schema) {
+  if (!schema || schema.length === 0) return [];
+  const failures = [];
+  for (const field of schema) {
+    if (!field.required) continue;
+    const value = payload?.[field.name];
+    if (value === void 0) {
+      failures.push({ event: eventKey, field: field.name, reason: "missing", expectedType: field.type });
+      continue;
+    }
+    if (value === null) {
+      failures.push({ event: eventKey, field: field.name, reason: "null", expectedType: field.type });
+    }
+  }
+  return failures;
+}
+function formatPayloadValidationError(failures) {
+  if (failures.length === 0) return "";
+  const parts = failures.map(
+    (f) => `${f.field} (${f.reason}${f.expectedType ? `, expected ${f.expectedType}` : ""})`
+  );
+  return `Payload validation failed for event '${failures[0].event}': ${parts.join("; ")}`;
+}
+function validatePayloadShapes(traits, emits) {
+  const mismatches = [];
+  const emitIndex = /* @__PURE__ */ new Map();
+  for (const [traitName, declarations] of emits) {
+    for (const decl of declarations) {
+      const fields = decl.payloadSchema?.map((p) => p.name) ?? [];
+      emitIndex.set(decl.event, { traitName, fields });
+    }
+  }
+  for (const trait of traits) {
+    if (!trait.listens) continue;
+    for (const listener of trait.listens) {
+      const emitter = emitIndex.get(listener.event);
+      if (!emitter) continue;
+      if (!listener.payloadMapping) continue;
+      const payloadRefs = extractPayloadReferences(listener.payloadMapping);
+      for (const ref of payloadRefs) {
+        if (!emitter.fields.includes(ref)) {
+          mismatches.push({
+            listenerTrait: trait.name,
+            emitterTrait: emitter.traitName,
+            event: listener.event,
+            referencedField: ref,
+            availableFields: emitter.fields
+          });
+        }
+      }
+    }
+  }
+  return mismatches;
+}
+function extractPayloadReferences(mapping) {
+  const refs = [];
+  function collect(value) {
+    if (typeof value === "string") {
+      const match = value.match(/^@payload\.(\w+)$/);
+      if (match) {
+        refs.push(match[1]);
+      }
+    } else if (typeof value === "object" && value !== null) {
+      if (Array.isArray(value)) {
+        value.forEach(collect);
+      } else {
+        Object.values(value).forEach(collect);
+      }
+    }
+  }
+  Object.values(mapping).forEach(collect);
+  return [...new Set(refs)];
+}
+function buildEmitsFromTraits(traits, explicitEmits) {
+  const result = new Map(explicitEmits ?? []);
+  for (const trait of traits) {
+    if (result.has(trait.name)) continue;
+    const emitDecls = [];
+    for (const transition of trait.transitions) {
+      if (!transition.effects) continue;
+      for (const effect of transition.effects) {
+        if (!Array.isArray(effect)) continue;
+        if (effect[0] === "emit" && typeof effect[1] === "string") {
+          const event = effect[1];
+          const payloadObj = effect[2];
+          const payloadSchema = payloadObj ? Object.keys(payloadObj).map((name) => ({ name })) : void 0;
+          if (!emitDecls.some((d) => d.event === event)) {
+            emitDecls.push({ event, payloadSchema });
+          }
+        }
+      }
+    }
+    if (emitDecls.length > 0) {
+      result.set(trait.name, emitDecls);
+    }
+  }
+  return result;
+}
 var MockPersistenceAdapter = class {
   stores = /* @__PURE__ */ new Map();
   schemas = /* @__PURE__ */ new Map();
@@ -3193,6 +3381,6 @@ var InMemoryPersistence = class {
   }
 };
 
-export { EffectExecutor, EventBus, HANDLER_MANIFEST, InMemoryPersistence, MockPersistenceAdapter, StateMachineManager, containsBindings, createContextFromBindings, createInitialTraitState, createMockPersistence, createTestExecutor, createUnifiedLoader, extractBindings, findInitialState, findTransition, getIsolatedCollectionName, getNamespacedEvent, interpolateProps, interpolateValue, isBrowser, isElectron, isNamespacedEvent, isNode, normalizeEventKey, parseNamespacedEvent, preprocessSchema, processEvent };
-//# sourceMappingURL=chunk-S5OLFFHT.js.map
-//# sourceMappingURL=chunk-S5OLFFHT.js.map
+export { EffectExecutor, EventBus, HANDLER_MANIFEST, InMemoryPersistence, MockPersistenceAdapter, StateMachineManager, buildEmitsFromTraits, containsBindings, createContextFromBindings, createInitialTraitState, createLogger, createMockPersistence, createTestExecutor, createUnifiedLoader, extractBindings, findInitialState, findTransition, formatPayloadValidationError, getIsolatedCollectionName, getNamespacedEvent, interpolateProps, interpolateValue, isBrowser, isElectron, isNamespacedEvent, isNode, normalizeEventKey, parseNamespacedEvent, preprocessSchema, processEvent, validateEventPayload, validatePayloadShapes };
+//# sourceMappingURL=chunk-OG2NHXES.js.map
+//# sourceMappingURL=chunk-OG2NHXES.js.map