@nextera.one/axis-server-sdk 2.3.12 → 2.3.14

package/dist/index.mjs

@@ -2364,21 +2364,71 @@ var init_axis_error = __esm({
   }
 });
 
-// src/engine/intent.router.ts
-var intent_router_exports = {};
-__export(intent_router_exports, {
-  IntentRouter: () => IntentRouter
-});
-import { decodeChainEnvelope, decodeChainRequest } from "@nextera.one/axis-protocol";
-function observerRefKey(ref) {
-  return typeof ref === "string" ? ref : ref.name;
+// src/engine/intent-builtins.ts
+function isBuiltinIntent(intent) {
+  return BUILTIN_INTENTS.has(intent);
 }
-function sensorRefKey(ref) {
-  return typeof ref === "string" ? ref : ref.name;
+function isChainExecIntent(intent) {
+  return intent === "CHAIN.EXEC" || intent === "axis.chain.exec";
 }
-function sensorBindingKey(binding) {
-  return `${binding.when}:${sensorRefKey(binding.ref)}`;
+function isIntentExecIntent(intent) {
+  return intent === "INTENT.EXEC" || intent === "axis.intent.exec";
+}
+function routeSystemBuiltinIntent(intent, body, encoder) {
+  if (intent === "system.ping" || intent === "public.ping") {
+    return {
+      ok: true,
+      effect: "pong",
+      headers: /* @__PURE__ */ new Map([[100, encoder.encode("AXIS_BACKEND_V1")]]),
+      body: encoder.encode(
+        JSON.stringify({
+          status: "ok",
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          version: "1.0.0"
+        })
+      )
+    };
+  }
+  if (intent === "system.time") {
+    const ts = Date.now().toString();
+    return {
+      ok: true,
+      effect: "time",
+      body: encoder.encode(
+        JSON.stringify({
+          ts,
+          iso: (/* @__PURE__ */ new Date()).toISOString()
+        })
+      )
+    };
+  }
+  if (intent === "system.echo") {
+    return {
+      ok: true,
+      effect: "echo",
+      body
+    };
+  }
+  return void 0;
 }
+var BUILTIN_INTENTS;
+var init_intent_builtins = __esm({
+  "src/engine/intent-builtins.ts"() {
+    BUILTIN_INTENTS = /* @__PURE__ */ new Set([
+      "system.ping",
+      "public.ping",
+      "system.time",
+      "system.echo",
+      "CHAIN.EXEC",
+      "axis.chain.exec",
+      "INTENT.EXEC",
+      "axis.intent.exec"
+    ]);
+  }
+});
+
+// src/engine/intent-proof-policy.ts
+import "reflect-metadata";
 function mergeProofKinds(...proofGroups) {
   const merged = /* @__PURE__ */ new Set();
   for (const proofs of proofGroups) {
@@ -2395,6 +2445,80 @@ function accessProofKinds(isPublic, isAnonymous, isAuthorized) {
   if (isAuthorized) proofs.push("AUTHORIZED");
   return proofs;
 }
+function resolveIntentProofPolicy(proto, methodName) {
+  const methodProof = Reflect.getMetadata(
+    REQUIRED_PROOF_METADATA_KEY,
+    proto,
+    methodName
+  );
+  const classProof = Reflect.getMetadata(
+    REQUIRED_PROOF_METADATA_KEY,
+    proto.constructor
+  );
+  const isPublicMethod = Reflect.getMetadata(
+    AXIS_PUBLIC_KEY,
+    proto,
+    methodName
+  );
+  const isPublicClass = Reflect.getMetadata(
+    AXIS_PUBLIC_KEY,
+    proto.constructor
+  );
+  const isAnonymousMethod = Reflect.getMetadata(
+    AXIS_ANONYMOUS_KEY,
+    proto,
+    methodName
+  );
+  const isAnonymousClass = Reflect.getMetadata(
+    AXIS_ANONYMOUS_KEY,
+    proto.constructor
+  );
+  const isAuthorizedMethod = Reflect.getMetadata(
+    AXIS_AUTHORIZED_KEY,
+    proto,
+    methodName
+  );
+  const isAuthorizedClass = Reflect.getMetadata(
+    AXIS_AUTHORIZED_KEY,
+    proto.constructor
+  );
+  const methodPolicyProof = mergeProofKinds(
+    methodProof,
+    accessProofKinds(isPublicMethod, isAnonymousMethod, isAuthorizedMethod)
+  );
+  const classPolicyProof = mergeProofKinds(
+    classProof,
+    accessProofKinds(isPublicClass, isAnonymousClass, isAuthorizedClass)
+  );
+  const requiredProof = methodPolicyProof.length ? methodPolicyProof : classPolicyProof;
+  return {
+    requiredProof,
+    isPublic: requiredProof.includes("NONE"),
+    isAnonymous: requiredProof.includes("ANONYMOUS"),
+    isAuthorized: requiredProof.includes("AUTHORIZED")
+  };
+}
+var init_intent_proof_policy = __esm({
+  "src/engine/intent-proof-policy.ts"() {
+    init_intent_policy_decorator();
+  }
+});
+
+// src/engine/intent.router.ts
+var intent_router_exports = {};
+__export(intent_router_exports, {
+  IntentRouter: () => IntentRouter
+});
+import { decodeChainEnvelope, decodeChainRequest } from "@nextera.one/axis-protocol";
+function observerRefKey(ref) {
+  return typeof ref === "string" ? ref : ref.name;
+}
+function sensorRefKey(ref) {
+  return typeof ref === "string" ? ref : ref.name;
+}
+function sensorBindingKey(binding) {
+  return `${binding.when}:${sensorRefKey(binding.ref)}`;
+}
 function mergeIntentSensorBindings(...sensorGroups) {
   const merged = /* @__PURE__ */ new Map();
   for (const group of sensorGroups) {
@@ -2450,7 +2574,7 @@ function normalizeChainConfig(decoratorConfig, intentConfig) {
     ...intentConfig
   };
 }
-var import_dto_schema, _IntentRouter, IntentRouter;
+var import_dto_schema, IntentRouter;
 var init_intent_router = __esm({
   "src/engine/intent.router.ts"() {
     init_handler_sensors_decorator();
@@ -2470,7 +2594,9 @@ var init_intent_router = __esm({
     init_cce_pipeline();
     init_axis_error();
     init_constants();
-    _IntentRouter = class _IntentRouter {
+    init_intent_builtins();
+    init_intent_proof_policy();
+    IntentRouter = class _IntentRouter {
       constructor(dependencyResolver, observerDispatcher, sensorRegistry) {
         this.logger = createAxisLogger(_IntentRouter.name);
         this.decoder = new TextDecoder();
@@ -2501,12 +2627,6 @@ var init_intent_router = __esm({
         this.intentContracts = /* @__PURE__ */ new Map();
         /** Per-intent required proof kinds */
         this.intentRequiredProof = /* @__PURE__ */ new Map();
-        /** Intents flagged as public (no auth required) */
-        this.publicIntents = /* @__PURE__ */ new Set();
-        /** Intents flagged as anonymous-session accessible */
-        this.anonymousIntents = /* @__PURE__ */ new Set();
-        /** Intents flagged as authorized-session accessible */
-        this.authorizedIntents = /* @__PURE__ */ new Set();
         /** Per-intent rate limit config */
         this.intentRateLimits = /* @__PURE__ */ new Map();
         /** CCE handler registry */
@@ -2537,10 +2657,10 @@ var init_intent_router = __esm({
       }
       has(intent) {
         const resolved = this.resolveIntentAlias(intent);
-        return this.handlers.has(resolved) || _IntentRouter.BUILTIN_INTENTS.has(resolved);
+        return this.handlers.has(resolved) || isBuiltinIntent(resolved);
       }
       getRegisteredIntents() {
-        return [..._IntentRouter.BUILTIN_INTENTS, ...this.handlers.keys()];
+        return [...BUILTIN_INTENTS, ...this.handlers.keys()];
       }
       getIntentEntry(intent) {
         const resolved = this.resolveIntentAlias(intent);
@@ -2549,7 +2669,7 @@ var init_intent_router = __esm({
           schema: this.intentSchemas.get(resolved),
           validators: this.intentValidators.get(resolved),
           hasSensors: this.intentSensors.has(resolved),
-          builtin: _IntentRouter.BUILTIN_INTENTS.has(resolved),
+          builtin: isBuiltinIntent(resolved),
           kind: this.intentKinds.get(resolved),
           chain: this.intentChains.get(resolved),
           capsulePolicy: this.intentCapsulePolicies.get(resolved),
@@ -2571,6 +2691,9 @@ var init_intent_router = __esm({
        * @param {any} handler - The handler function or object
        */
       register(intent, handler) {
+        if (this.handlers.has(intent)) {
+          this.logger.warn(`Intent ${intent} is already registered; replacing handler`);
+        }
         this.handlers.set(intent, handler);
         if (typeof handler === "function" && handler.name) {
           this.intentHandlerRefs.set(intent, handler.name);
@@ -2655,9 +2778,14 @@ var init_intent_router = __esm({
        * Routes a decoded AXIS frame to the appropriate handler.
        *
        * **Precedence:**
-       * 1. System Built-ins (`system.ping`, `public.ping`, `system.time`, `system.echo`)
-       * 2. Meta-intent execution (`INTENT.EXEC` / `axis.intent.exec`)
-       * 3. Dynamically registered handlers from modules.
+       * 1. SDK meta-intents (`CHAIN.EXEC`, `INTENT.EXEC`)
+       * 2. Dynamically registered handlers from modules
+       * 3. Simple SDK built-in fallback (`system.ping`, `public.ping`, `system.time`, `system.echo`)
+       *
+       * Registered app handlers intentionally win over simple built-ins. This lets
+       * applications attach sensors, rate limits, and custom responses to intents
+       * like `system.ping` while keeping a default fallback for apps that do not
+       * register their own handler.
        *
        * @param {AxisFrame} frame - The validated and decoded binary frame
        * @returns {Promise<AxisEffect>} The resulting effect of the execution
@@ -2681,128 +2809,7 @@ var init_intent_router = __esm({
             frame
           });
           let effect;
-          if (intent === "system.ping" || intent === "public.ping") {
-            this.logger.debug("PING received");
-            effect = {
-              ok: true,
-              effect: "pong",
-              headers: /* @__PURE__ */ new Map([
-                [100, new TextEncoder().encode("AXIS_BACKEND_V1")]
-              ]),
-              body: new TextEncoder().encode(
-                JSON.stringify({
-                  status: "ok",
-                  timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-                  version: "1.0.0"
-                })
-              )
-            };
-          } else if (intent === "system.time") {
-            const ts = Date.now().toString();
-            effect = {
-              ok: true,
-              effect: "time",
-              body: new TextEncoder().encode(
-                JSON.stringify({
-                  ts,
-                  iso: (/* @__PURE__ */ new Date()).toISOString()
-                })
-              )
-            };
-          } else if (intent === "system.echo") {
-            effect = {
-              ok: true,
-              effect: "echo",
-              body: frame.body
-            };
-          } else if (intent === "CHAIN.EXEC" || intent === "axis.chain.exec") {
-            const chainRequest = this.parseChainRequestBody(frame.body);
-            effect = await this.executeChainRequest(frame, chainRequest);
-          } else if (intent === "INTENT.EXEC" || intent === "axis.intent.exec") {
-            const execBody = this.parseIntentExecBody(frame.body);
-            const innerIntent = execBody.intent;
-            const innerArgs = execBody.args || {};
-            if (!innerIntent) {
-              throw new Error("INTENT.EXEC missing inner intent");
-            }
-            this.logger.debug(`EXEC: routing to inner intent '${innerIntent}'`);
-            const innerHeaders = new Map(frame.headers);
-            innerHeaders.set(TLV_INTENT, this.encoder.encode(innerIntent));
-            const inlineCapsule = this.toInlineCapsuleRecord(execBody.capsule);
-            const capsuleId = this.extractInlineCapsuleId(inlineCapsule);
-            if (capsuleId) {
-              innerHeaders.set(TLV_CAPSULE, this.encoder.encode(capsuleId));
-              innerHeaders.set(TLV_PROOF_REF, this.encoder.encode(capsuleId));
-            }
-            const innerFrame = withAxisExecutionContext(
-              {
-                ...frame,
-                headers: innerHeaders,
-                body: this.encodeJson(innerArgs)
-              },
-              mergeAxisExecutionContext(getAxisExecutionContext(frame), {
-                metaIntent: "INTENT.EXEC",
-                actorId: this.getActorIdFromFrame(frame),
-                inlineCapsule
-              }) || {}
-            );
-            effect = await this.route(innerFrame);
-          } else {
-            const handler = this.handlers.get(intent);
-            if (!handler) {
-              throw new Error(`Intent not found: ${intent}`);
-            }
-            const sensorBindings = this.intentSensors.get(intent);
-            if (sensorBindings && sensorBindings.length > 0) {
-              await this.runIntentSensors(sensorBindings, intent, frame, "before");
-            }
-            const decoder = this.intentDecoders.get(intent);
-            let decodedBody = frame.body;
-            if (decoder) {
-              try {
-                decodedBody = decoder(Buffer.from(frame.body));
-              } catch (decodeErr) {
-                throw new Error(
-                  `IntentBody decode failed for ${intent}: ${decodeErr.message}`
-                );
-              }
-            }
-            this.enforceCapsulePolicy(
-              intent,
-              frame,
-              decodedBody,
-              this.getEffectiveCapsulePolicy(intent, frame)
-            );
-            if (typeof handler === "function") {
-              const resultBody = decoder ? await handler(decodedBody, frame.headers) : await handler(frame.body, frame.headers);
-              effect = {
-                ok: true,
-                effect: "complete",
-                body: resultBody
-              };
-            } else {
-              if (typeof handler.handle === "function") {
-                effect = await handler.handle(frame);
-              } else if (typeof handler.execute === "function") {
-                const bodyRes = decoder ? await handler.execute(decodedBody, frame.headers) : await handler.execute(frame.body, frame.headers);
-                effect = {
-                  ok: true,
-                  effect: "complete",
-                  body: bodyRes
-                };
-              } else {
-                throw new Error(
-                  `Handler for ${intent} does not implement handle or execute`
-                );
-              }
-            }
-            if (sensorBindings && sensorBindings.length > 0) {
-              await this.runIntentSensors(sensorBindings, intent, frame, "after", {
-                decodedBody,
-                effect
-              });
-            }
-          }
+          effect = await this.routeResolvedIntent(intent, frame);
           await this.emitIntentObservers(observerBindings, {
             event: "intent.completed",
             timestamp: Date.now(),
@@ -2827,6 +2834,137 @@ var init_intent_router = __esm({
           throw e;
         }
       }
+      /**
+       * Dispatches a resolved canonical intent to the correct execution path.
+       * This keeps route() focused on observer/error lifecycle concerns.
+       */
+      async routeResolvedIntent(intent, frame) {
+        if (isChainExecIntent(intent)) {
+          const chainRequest = this.parseChainRequestBody(frame.body);
+          return this.executeChainRequest(frame, chainRequest);
+        }
+        if (isIntentExecIntent(intent)) {
+          return this.routeIntentExec(frame);
+        }
+        if (this.handlers.has(intent)) {
+          return this.routeRegisteredIntent(intent, frame);
+        }
+        const builtinEffect = routeSystemBuiltinIntent(
+          intent,
+          frame.body,
+          this.encoder
+        );
+        if (builtinEffect) {
+          if (intent === "system.ping" || intent === "public.ping") {
+            this.logger.debug("PING received");
+          }
+          return builtinEffect;
+        }
+        return this.routeRegisteredIntent(intent, frame);
+      }
+      /**
+       * Handles INTENT.EXEC by building an inner frame and routing it normally.
+       * The recursive route call is intentional so sensors/observers/policies for
+       * the inner intent stay identical to a direct request.
+       */
+      async routeIntentExec(frame) {
+        const execBody = this.parseIntentExecBody(frame.body);
+        const innerIntent = execBody.intent;
+        const innerArgs = execBody.args || {};
+        if (!innerIntent) {
+          throw new Error("INTENT.EXEC missing inner intent");
+        }
+        this.logger.debug(`EXEC: routing to inner intent '${innerIntent}'`);
+        const innerHeaders = new Map(frame.headers);
+        innerHeaders.set(TLV_INTENT, this.encoder.encode(innerIntent));
+        const inlineCapsule = this.toInlineCapsuleRecord(execBody.capsule);
+        const capsuleId = this.extractInlineCapsuleId(inlineCapsule);
+        if (capsuleId) {
+          innerHeaders.set(TLV_CAPSULE, this.encoder.encode(capsuleId));
+          innerHeaders.set(TLV_PROOF_REF, this.encoder.encode(capsuleId));
+        }
+        const innerFrame = withAxisExecutionContext(
+          {
+            ...frame,
+            headers: innerHeaders,
+            body: this.encodeJson(innerArgs)
+          },
+          mergeAxisExecutionContext(getAxisExecutionContext(frame), {
+            metaIntent: "INTENT.EXEC",
+            actorId: this.getActorIdFromFrame(frame),
+            inlineCapsule
+          }) || {}
+        );
+        return this.route(innerFrame);
+      }
+      /**
+       * Executes an app-registered intent: before sensors, body decode, capsule
+       * policy, handler invocation, then after sensors.
+       */
+      async routeRegisteredIntent(intent, frame) {
+        const handler = this.handlers.get(intent);
+        if (!handler) {
+          throw new Error(`Intent not found: ${intent}`);
+        }
+        const sensorBindings = this.intentSensors.get(intent);
+        if (sensorBindings && sensorBindings.length > 0) {
+          await this.runIntentSensors(sensorBindings, intent, frame, "before");
+        }
+        const decoder = this.intentDecoders.get(intent);
+        const decodedBody = this.decodeIntentBody(intent, frame, decoder);
+        this.enforceCapsulePolicy(
+          intent,
+          frame,
+          decodedBody,
+          this.getEffectiveCapsulePolicy(intent, frame)
+        );
+        const effect = await this.invokeRegisteredHandler(
+          intent,
+          handler,
+          frame,
+          decoder,
+          decodedBody
+        );
+        if (sensorBindings && sensorBindings.length > 0) {
+          await this.runIntentSensors(sensorBindings, intent, frame, "after", {
+            decodedBody,
+            effect
+          });
+        }
+        return effect;
+      }
+      decodeIntentBody(intent, frame, decoder) {
+        if (!decoder) return frame.body;
+        try {
+          return decoder(Buffer.from(frame.body));
+        } catch (decodeErr) {
+          throw new Error(
+            `IntentBody decode failed for ${intent}: ${decodeErr.message}`
+          );
+        }
+      }
+      async invokeRegisteredHandler(intent, handler, frame, decoder, decodedBody) {
+        if (typeof handler === "function") {
+          const resultBody = decoder ? await handler(decodedBody, frame.headers) : await handler(frame.body, frame.headers);
+          return {
+            ok: true,
+            effect: "complete",
+            body: resultBody
+          };
+        }
+        if (typeof handler.handle === "function") {
+          return handler.handle(frame);
+        }
+        if (typeof handler.execute === "function") {
+          const bodyRes = decoder ? await handler.execute(decodedBody, frame.headers) : await handler.execute(frame.body, frame.headers);
+          return {
+            ok: true,
+            effect: "complete",
+            body: bodyRes
+          };
+        }
+        throw new Error(`Handler for ${intent} does not implement handle or execute`);
+      }
       logIntent(intent, start, ok, error) {
         const diff = process.hrtime(start);
         const ms = (diff[0] * 1e3 + diff[1] / 1e6).toFixed(2);
@@ -2920,62 +3058,9 @@ var init_intent_router = __esm({
         if (contract) {
           this.intentContracts.set(intent, contract);
         }
-        const methodProof = Reflect.getMetadata(
-          REQUIRED_PROOF_METADATA_KEY,
-          proto,
-          methodName
-        );
-        const classProof = Reflect.getMetadata(
-          REQUIRED_PROOF_METADATA_KEY,
-          proto.constructor
-        );
-        const isPublicMethod = Reflect.getMetadata(
-          AXIS_PUBLIC_KEY,
-          proto,
-          methodName
-        );
-        const isPublicClass = Reflect.getMetadata(
-          AXIS_PUBLIC_KEY,
-          proto.constructor
-        );
-        const isAnonMethod = Reflect.getMetadata(
-          AXIS_ANONYMOUS_KEY,
-          proto,
-          methodName
-        );
-        const isAnonClass = Reflect.getMetadata(
-          AXIS_ANONYMOUS_KEY,
-          proto.constructor
-        );
-        const isAuthorizedMethod = Reflect.getMetadata(
-          AXIS_AUTHORIZED_KEY,
-          proto,
-          methodName
-        );
-        const isAuthorizedClass = Reflect.getMetadata(
-          AXIS_AUTHORIZED_KEY,
-          proto.constructor
-        );
-        const methodPolicyProof = mergeProofKinds(
-          methodProof,
-          accessProofKinds(isPublicMethod, isAnonMethod, isAuthorizedMethod)
-        );
-        const classPolicyProof = mergeProofKinds(
-          classProof,
-          accessProofKinds(isPublicClass, isAnonClass, isAuthorizedClass)
-        );
-        const requiredProof = methodPolicyProof.length ? methodPolicyProof : classPolicyProof;
-        if (requiredProof.length > 0) {
-          this.intentRequiredProof.set(intent, requiredProof);
-        }
-        if (requiredProof.includes("NONE")) {
-          this.publicIntents.add(intent);
-        }
-        if (requiredProof.includes("ANONYMOUS")) {
-          this.anonymousIntents.add(intent);
-        }
-        if (requiredProof.includes("AUTHORIZED")) {
-          this.authorizedIntents.add(intent);
+        const proofPolicy = resolveIntentProofPolicy(proto, methodName);
+        if (proofPolicy.requiredProof.length > 0) {
+          this.intentRequiredProof.set(intent, proofPolicy.requiredProof);
         }
         const rateLimit = Reflect.getMetadata(
           AXIS_RATE_LIMIT_KEY,
@@ -2997,13 +3082,13 @@ var init_intent_router = __esm({
         return this.intentRequiredProof.get(this.resolveIntentAlias(intent));
       }
       isPublic(intent) {
-        return this.publicIntents.has(this.resolveIntentAlias(intent));
+        return this.getRequiredProof(intent)?.includes("NONE") ?? false;
       }
       isAnonymous(intent) {
-        return this.anonymousIntents.has(this.resolveIntentAlias(intent));
+        return this.getRequiredProof(intent)?.includes("ANONYMOUS") ?? false;
       }
       isAuthorized(intent) {
-        return this.authorizedIntents.has(this.resolveIntentAlias(intent));
+        return this.getRequiredProof(intent)?.includes("AUTHORIZED") ?? false;
       }
       getRateLimit(intent) {
         return this.intentRateLimits.get(this.resolveIntentAlias(intent));
@@ -3024,7 +3109,7 @@ var init_intent_router = __esm({
       }
       /** The system/builtin intents (ping, time, echo, chain, intent.exec). */
       getSystemIntents() {
-        return [..._IntentRouter.BUILTIN_INTENTS];
+        return [...BUILTIN_INTENTS];
       }
       /** True if every intent in the handler is public, or any one is public — returns true if ANY intent is @AxisPublic. */
       isHandlerPublic(handlerName) {
@@ -3097,7 +3182,7 @@ var init_intent_router = __esm({
        * canonical intent. Existing exact intent names always win.
        */
       resolveIntentAlias(intent) {
-        if (this.handlers.has(intent) || _IntentRouter.BUILTIN_INTENTS.has(intent)) {
+        if (this.handlers.has(intent) || isBuiltinIntent(intent)) {
           return intent;
         }
         const separator = "...";
@@ -3621,18 +3706,6 @@ var init_intent_router = __esm({
         this.intentSchemas.set(meta.intent, schema);
       }
     };
-    /** Intents handled inline in route() — not in `handlers` map */
-    _IntentRouter.BUILTIN_INTENTS = /* @__PURE__ */ new Set([
-      "system.ping",
-      "public.ping",
-      "system.time",
-      "system.echo",
-      "CHAIN.EXEC",
-      "axis.chain.exec",
-      "INTENT.EXEC",
-      "axis.intent.exec"
-    ]);
-    IntentRouter = _IntentRouter;
   }
 });