@almadar/runtime 3.1.4 → 3.2.1

package/dist/ServerBridge.d.ts

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

package/dist/{chunk-6PAKTVTR.js → chunk-PXASRZKG.js}

@@ -177,6 +177,14 @@ function createLogger(namespace) {
 
 // src/BindingResolver.ts
 var bindLog = createLogger("almadar:runtime:bindings");
+var CLIENT_ONLY_BINDING_ROOTS = /* @__PURE__ */ new Set(["trait"]);
+function isClientOnlyBinding(value) {
+  if (!value.startsWith("@")) return false;
+  const afterAt = value.slice(1);
+  const firstDot = afterAt.indexOf(".");
+  const root = firstDot === -1 ? afterAt : afterAt.slice(0, firstDot);
+  return CLIENT_ONLY_BINDING_ROOTS.has(root);
+}
 function interpolateProps(props, ctx) {
   const result = {};
   for (const [key, value] of Object.entries(props)) {
@@ -201,6 +209,10 @@ function interpolateValue(value, ctx) {
 }
 function interpolateString(value, ctx) {
   if (value.startsWith("@") && isPureBinding(value)) {
+    if (isClientOnlyBinding(value)) {
+      bindLog.debug("passthrough:client-only", { binding: value });
+      return value;
+    }
     const resolved = resolveBinding(value, ctx);
     bindLog.debug("resolve", { binding: value, resolvedType: typeof resolved });
     return resolved;
@@ -215,6 +227,9 @@ function isPureBinding(value) {
 }
 function interpolateEmbeddedBindings(value, ctx) {
   return value.replace(/@[\w]+(?:\.[\w]+)*/g, (match) => {
+    if (isClientOnlyBinding(match)) {
+      return match;
+    }
     const resolved = resolveBinding(match, ctx);
     return resolved !== void 0 ? String(resolved) : match;
   });
@@ -886,13 +901,13 @@ var EffectExecutor = class {
     }
     const { operator, args } = parsed;
     const isCompound = operator === "do" || operator === "when";
-    const isSet3Elem = operator === "set" && args.length === 2 && typeof args[0] === "string" && args[0].startsWith("@entity.");
+    const isSetPathForm = operator === "set" && args.length >= 2 && typeof args[0] === "string" && args[0].startsWith("@entity.");
     let resolvedArgs;
     if (isCompound) {
       resolvedArgs = args;
-    } else if (isSet3Elem) {
+    } else if (isSetPathForm) {
       const ctx = createContextFromBindings(this.bindings, this.strictBindings, this.contextExtensions);
-      resolvedArgs = [args[0], interpolateValue(args[1], ctx)];
+      resolvedArgs = [args[0], ...args.slice(1).map((a) => interpolateValue(a, ctx))];
     } else {
       resolvedArgs = resolveArgs(args, this.bindings, this.strictBindings, this.contextExtensions);
     }
@@ -972,6 +987,59 @@ var EffectExecutor = class {
     return results;
   }
   // ==========================================================================
+  // `emit:` config extraction — close-the-circuit on async/reactive ops.
+  //
+  // `fetch`, `persist`, `call-service`, `set`, `ref`, `os/watch-*` may carry
+  // an `emit:` key in their options object. After the effect's work finishes,
+  // the runtime fires the author-configured bus event so downstream state
+  // machines can branch on success/failure without stitching async/sequence.
+  //
+  // See `docs/Almadar_Std_Gaps.md` §3.1 and the emit-config plan for the
+  // semantics. The compiled-path shell does the same work in generated JS.
+  // ==========================================================================
+  extractEmitConfig(rawOpt) {
+    if (!rawOpt || typeof rawOpt !== "object" || Array.isArray(rawOpt)) {
+      return void 0;
+    }
+    const obj = rawOpt;
+    const emitBlock = obj.emit;
+    if (!emitBlock || typeof emitBlock !== "object" || Array.isArray(emitBlock)) {
+      return void 0;
+    }
+    const block = emitBlock;
+    const asStr = (v) => typeof v === "string" ? v : void 0;
+    return {
+      success: asStr(block.success),
+      failure: asStr(block.failure),
+      on_change: asStr(block.on_change) ?? asStr(block.onChange),
+      on_message: asStr(block.on_message) ?? asStr(block.onMessage)
+    };
+  }
+  emitSuccess(emit, key, payload) {
+    const eventName = emit?.[key];
+    if (eventName) {
+      this.handlers.emit(eventName, payload);
+    }
+  }
+  emitFailure(emit, err) {
+    if (!emit?.failure) return;
+    const error = err instanceof Error ? err.message : String(err);
+    this.handlers.emit(emit.failure, { error });
+  }
+  /**
+   * Narrow the generic emit config into the `os/watch-*` handler surface
+   * (only `on_message` + `failure` are meaningful for streaming ops).
+   * Returns `undefined` when neither field is set so handlers can test
+   * with a single `if (emit)` guard.
+   */
+  osEmit(emit) {
+    if (!emit || !emit.on_message && !emit.failure) return void 0;
+    return {
+      on_message: emit.on_message,
+      failure: emit.failure
+    };
+  }
+  // ==========================================================================
   // Effect Dispatch
   // ==========================================================================
   async dispatch(operator, args) {
@@ -988,10 +1056,12 @@ var EffectExecutor = class {
         let entityId;
         let field;
         let value;
-        if (args.length === 2 && typeof args[0] === "string" && args[0].startsWith("@entity.")) {
+        let emitCfg;
+        if (typeof args[0] === "string" && args[0].startsWith("@entity.")) {
           const path = args[0];
           field = path.slice("@entity.".length);
           value = args[1];
+          emitCfg = this.extractEmitConfig(args[2]);
           entityId = typeof entity?.["id"] === "string" ? entity["id"] : void 0;
           if (!entityId) {
             effectLog.warn("set:missing-entity-id", { path });
@@ -1001,22 +1071,33 @@ var EffectExecutor = class {
           entityId = args[0];
           field = args[1];
           value = args[2];
+          emitCfg = this.extractEmitConfig(args[3]);
         }
         this.handlers.set(entityId, field, value);
         if (entity && entity["id"] === entityId) {
           entity[field] = value;
         }
+        this.emitSuccess(emitCfg, "success", value);
         break;
       }
       case "persist": {
         const action = args[0];
-        if (action === "batch") {
-          const operations = args[1];
-          await this.handlers.persist("batch", "", { operations });
-        } else {
-          const entityType = args[1];
-          const data = args[2];
-          await this.handlers.persist(action, entityType, data);
+        const last = args[args.length - 1];
+        const emitCfg = last && typeof last === "object" && !Array.isArray(last) && "emit" in last ? this.extractEmitConfig(last) : void 0;
+        try {
+          if (action === "batch") {
+            const operations = args[1];
+            await this.handlers.persist("batch", "", { operations });
+            this.emitSuccess(emitCfg, "success", operations);
+          } else {
+            const entityType = args[1];
+            const data = args[2];
+            await this.handlers.persist(action, entityType, data);
+            this.emitSuccess(emitCfg, "success", data);
+          }
+        } catch (err) {
+          this.emitFailure(emitCfg, err);
+          throw err;
         }
         break;
       }
@@ -1024,7 +1105,14 @@ var EffectExecutor = class {
         const service = args[0];
         const action = args[1];
         const params = args[2];
-        await this.handlers.callService(service, action, params);
+        const emitCfg = this.extractEmitConfig(args[3]);
+        try {
+          const result = await this.handlers.callService(service, action, params);
+          this.emitSuccess(emitCfg, "success", result);
+        } catch (err) {
+          this.emitFailure(emitCfg, err);
+          throw err;
+        }
         break;
       }
       case "fetch": {
@@ -1032,7 +1120,14 @@ var EffectExecutor = class {
           const entityType = args[0];
           const rawOpt = args[1];
           const options = typeof rawOpt === "string" ? { id: rawOpt } : rawOpt;
-          await this.handlers.fetch(entityType, options);
+          const emitCfg = this.extractEmitConfig(rawOpt);
+          try {
+            const result = await this.handlers.fetch(entityType, options);
+            this.emitSuccess(emitCfg, "success", result);
+          } catch (err) {
+            this.emitFailure(emitCfg, err);
+            throw err;
+          }
         } else {
           this.logUnsupported("fetch");
         }
@@ -1043,12 +1138,20 @@ var EffectExecutor = class {
         const refEntityType = args[0];
         const rawRefOpt = args[1];
         const refOptions = typeof rawRefOpt === "string" ? { id: rawRefOpt } : rawRefOpt;
-        if (this.handlers.ref) {
-          await this.handlers.ref(refEntityType, refOptions);
-        } else if (this.handlers.fetch) {
-          await this.handlers.fetch(refEntityType, refOptions);
-        } else {
-          this.logUnsupported("ref");
+        const refEmitCfg = this.extractEmitConfig(rawRefOpt);
+        try {
+          let result = void 0;
+          if (this.handlers.ref) {
+            result = await this.handlers.ref(refEntityType, refOptions);
+          } else if (this.handlers.fetch) {
+            result = await this.handlers.fetch(refEntityType, refOptions);
+          } else {
+            this.logUnsupported("ref");
+          }
+          this.emitSuccess(refEmitCfg, "on_change", result);
+        } catch (err) {
+          this.emitFailure(refEmitCfg, err);
+          throw err;
         }
         break;
       }
@@ -1185,11 +1288,18 @@ var EffectExecutor = class {
         break;
       }
       // OS trigger operators (server-side only)
+      //
+      // Each may carry `emit:` inside a trailing options object. The
+      // executor extracts it and passes it to the handler so the
+      // hardcoded fallback name (e.g. OS_CRON_FIRE) is replaced by the
+      // author-configured event.
       case "os/watch-files": {
         if (this.handlers.osWatchFiles) {
           const glob = args[0];
-          const options = args[1];
-          this.handlers.osWatchFiles(glob, options ?? {});
+          const rawOptions = args[1];
+          const emitCfg = this.extractEmitConfig(rawOptions);
+          const options = rawOptions ? { recursive: rawOptions.recursive, debounce: rawOptions.debounce } : {};
+          this.handlers.osWatchFiles(glob, options, this.osEmit(emitCfg));
         } else {
           this.logUnsupported("os/watch-files");
         }
@@ -1197,7 +1307,12 @@ var EffectExecutor = class {
       }
       case "os/watch-process": {
         if (this.handlers.osWatchProcess) {
-          this.handlers.osWatchProcess(args[0], args[1]);
+          const emitCfg = this.extractEmitConfig(args[2]);
+          this.handlers.osWatchProcess(
+            args[0],
+            args[1],
+            this.osEmit(emitCfg)
+          );
         } else {
           this.logUnsupported("os/watch-process");
         }
@@ -1205,7 +1320,12 @@ var EffectExecutor = class {
       }
       case "os/watch-port": {
         if (this.handlers.osWatchPort) {
-          this.handlers.osWatchPort(args[0], args[1] ?? "tcp");
+          const emitCfg = this.extractEmitConfig(args[2]);
+          this.handlers.osWatchPort(
+            args[0],
+            args[1] ?? "tcp",
+            this.osEmit(emitCfg)
+          );
         } else {
           this.logUnsupported("os/watch-port");
         }
@@ -1213,7 +1333,12 @@ var EffectExecutor = class {
       }
       case "os/watch-http": {
         if (this.handlers.osWatchHttp) {
-          this.handlers.osWatchHttp(args[0], args[1]);
+          const emitCfg = this.extractEmitConfig(args[2]);
+          this.handlers.osWatchHttp(
+            args[0],
+            args[1],
+            this.osEmit(emitCfg)
+          );
         } else {
           this.logUnsupported("os/watch-http");
         }
@@ -1221,7 +1346,8 @@ var EffectExecutor = class {
       }
       case "os/watch-cron": {
         if (this.handlers.osWatchCron) {
-          this.handlers.osWatchCron(args[0]);
+          const emitCfg = this.extractEmitConfig(args[1]);
+          this.handlers.osWatchCron(args[0], this.osEmit(emitCfg));
         } else {
           this.logUnsupported("os/watch-cron");
         }
@@ -1229,7 +1355,8 @@ var EffectExecutor = class {
       }
       case "os/watch-signal": {
         if (this.handlers.osWatchSignal) {
-          this.handlers.osWatchSignal(args[0]);
+          const emitCfg = this.extractEmitConfig(args[1]);
+          this.handlers.osWatchSignal(args[0], this.osEmit(emitCfg));
         } else {
           this.logUnsupported("os/watch-signal");
         }
@@ -1237,7 +1364,8 @@ var EffectExecutor = class {
       }
       case "os/watch-env": {
         if (this.handlers.osWatchEnv) {
-          this.handlers.osWatchEnv(args[0]);
+          const emitCfg = this.extractEmitConfig(args[1]);
+          this.handlers.osWatchEnv(args[0], this.osEmit(emitCfg));
         } else {
           this.logUnsupported("os/watch-env");
         }
@@ -2559,5 +2687,5 @@ function parseNamespacedEvent(eventName) {
 }
 
 export { EffectExecutor, EventBus, HANDLER_MANIFEST, StateMachineManager, containsBindings, createContextFromBindings, createInitialTraitState, createTestExecutor, createUnifiedLoader, extractBindings, findInitialState, findTransition, getIsolatedCollectionName, getNamespacedEvent, interpolateProps, interpolateValue, isNamespacedEvent, normalizeEventKey, parseNamespacedEvent, preprocessSchema, processEvent };
-//# sourceMappingURL=chunk-6PAKTVTR.js.map
-//# sourceMappingURL=chunk-6PAKTVTR.js.map
+//# sourceMappingURL=chunk-PXASRZKG.js.map
+//# sourceMappingURL=chunk-PXASRZKG.js.map