@fabricorg/platform-host 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @fabricorg/platform-host
 
+## 0.4.2 — 2026-07-20
+
+- Reject handler-emitted domain events absent from the action's `emitsEvents` declaration.
+
+## 0.4.1 — 2026-07-20
+
+- Add runtime-local action resolution without process-wide registry mutation.
+- Pass the injected host clock to policy evaluators.
+- Treat empty state-machine targets as no-op transitions.
+- Default domain events to the action schema version while preserving explicit event versions.
+- Omit custom extracted-event carrier fields from durable invocation results.
+
 ## 0.4.0 — 2026-07-19
 
 - Add an optional agent-only HITL evaluator between schema validation and ordinary policies.

package/README.md

@@ -3,7 +3,7 @@
 The canonical host for the `@fabricorg/platform` mutation pipeline.
 
 ```bash
-pnpm add @fabricorg/platform@^0.7.0 @fabricorg/platform-host@^0.4.0
+pnpm add @fabricorg/platform@^0.7.0 @fabricorg/platform-host@^0.4.1
 ```
 
 Vertical packages register `FabricModule` definitions. Host applications provide tenant authorization,
@@ -18,6 +18,13 @@ Actor → ActionInvocation → Schema → Agent HITL → PolicyEvaluation → St
 worker entry point. With no dispatcher the host executes inline, which is intended for tests and local
 development only.
 
+Applications that assemble action catalogs per runtime can provide `resolveAction` instead of
+mutating the process-wide platform registry. A custom `extractEvents` implementation can pair with
+`eventResultFields` so its event carrier is removed from the durable invocation result. Domain events
+without an explicit `eventSchemaVersion` inherit the action version, while host lifecycle events stay
+at version 1. Emitted domain events must appear in the action's `emitsEvents` declaration. The
+injected `now` clock is also passed to ordinary policy evaluation.
+
 Production polling workers can use `createStoreBackedActionDispatcher()` plus
 `runPlatformActionWorker()`. The pending invocation row is the durable queue item; workers claim
 bounded batches with an atomic lease and `FOR UPDATE SKIP LOCKED`, and an expired `running` lease is

package/dist/index.cjs

@@ -12,8 +12,10 @@ function createGovernedActionHost(options) {
   for (const adapter of options.adapters ?? []) adapters.register(adapter);
   const now = options.now ?? (() => /* @__PURE__ */ new Date());
   const extractEvents = options.extractEvents ?? DEFAULT_EXTRACT_EVENTS;
+  const actionResolver = options.resolveAction ?? platform.resolveAction;
+  const eventResultFields = options.eventResultFields ?? ["_events"];
   async function submitAction(input) {
-    const action = platform.resolveAction(input.actionId);
+    const action = actionResolver(input.actionId);
     if (!action) throw new Error(`Unknown action: ${input.actionId}`);
     const authorizationInput = toAuthorizationInput(action, input);
     if (!await options.authorization.checkEntitlement(authorizationInput)) {
@@ -105,7 +107,7 @@ function createGovernedActionHost(options) {
         error: `Invocation is leased by ${invocation.leaseOwner}`
       };
     }
-    const action = platform.resolveAction(invocation.actionId);
+    const action = actionResolver(invocation.actionId);
     if (!action) {
       return fail(invocation, "failed", `Unknown action: ${invocation.actionId}`);
     }
@@ -193,7 +195,8 @@ function createGovernedActionHost(options) {
         parameters: parsed.data,
         db: options.store.db,
         services: options.services,
-        mode: "execute"
+        mode: "execute",
+        now: now()
       });
       for (const outcome of outcomes) {
         await options.store.appendPolicyEvaluation({
@@ -226,15 +229,17 @@ function createGovernedActionHost(options) {
           entityId
         ) ?? initialState(binding.entityType) : initialState(binding.entityType);
         const targetState = typeof binding.targetState === "function" ? binding.targetState(parsed.data) : binding.targetState;
-        const transition = platform.validateTransition(
-          binding.entityType,
-          currentState,
-          targetState,
-          action.actionId
-        );
-        const replayingAppliedTransition = action.idempotent && currentState === targetState;
-        if (!transition.valid && !replayingAppliedTransition) {
-          return fail(invocation, "failed", transition.error ?? "Invalid state transition");
+        if (targetState !== "") {
+          const transition = platform.validateTransition(
+            binding.entityType,
+            currentState,
+            targetState,
+            action.actionId
+          );
+          const replayingAppliedTransition = action.idempotent && currentState === targetState;
+          if (!transition.valid && !replayingAppliedTransition) {
+            return fail(invocation, "failed", transition.error ?? "Invalid state transition");
+          }
         }
       }
       let data;
@@ -261,9 +266,19 @@ function createGovernedActionHost(options) {
         }
         data = handlerResult.data ?? {};
         domainEvents = extractEvents(data);
+        const undeclaredEvent = domainEvents.find(
+          (event) => !action.emitsEvents.includes(event.eventType)
+        );
+        if (undeclaredEvent) {
+          return fail(
+            invocation,
+            "failed",
+            `${action.actionId} emitted undeclared event type ${undeclaredEvent.eventType}`
+          );
+        }
         if (action.eventPhase !== "after_adapters") {
           for (const [index, event] of domainEvents.entries()) {
-            await appendEvent(invocation, event, `domain:${index}`);
+            await appendEvent(invocation, event, `domain:${index}`, action.version);
           }
         }
       } catch (error) {
@@ -382,10 +397,10 @@ function createGovernedActionHost(options) {
       }
       if (action.eventPhase === "after_adapters") {
         for (const [index, event] of domainEvents.entries()) {
-          await appendEvent(invocation, event, `domain:${index}`);
+          await appendEvent(invocation, event, `domain:${index}`, action.version);
         }
       }
-      const result = withoutPrivateHostFields(data);
+      const result = withoutPrivateHostFields(data, eventResultFields);
       await options.store.updateActionInvocation(actionInvocationId, tenantId, spaceId, {
         status: "completed",
         result
@@ -416,7 +431,7 @@ function createGovernedActionHost(options) {
         error: `Invocation is not waiting for approval (status: ${invocation.status})`
       };
     }
-    const action = platform.resolveAction(invocation.actionId);
+    const action = actionResolver(invocation.actionId);
     if (!action) return fail(invocation, "failed", `Unknown action: ${invocation.actionId}`);
     const approvalAuthorizationInput = toAuthorizationInput(action, {
       tenantId,
@@ -464,14 +479,14 @@ function createGovernedActionHost(options) {
     if (!decision.approved) return actionResult(transitioned);
     return executeInvocation(actionInvocationId, tenantId, spaceId, { leaseOwner });
   }
-  async function appendEvent(invocation, event, deduplicationKey) {
+  async function appendEvent(invocation, event, deduplicationKey, defaultEventSchemaVersion = 1) {
     const timestamp = now();
     const envelope = {
       id: lifecycleId("evt", invocation.id, deduplicationKey),
       tenantId: invocation.tenantId,
       spaceId: invocation.spaceId,
       eventType: event.eventType,
-      eventSchemaVersion: event.eventSchemaVersion ?? 1,
+      eventSchemaVersion: event.eventSchemaVersion ?? defaultEventSchemaVersion,
       subjectType: event.subjectType,
       subjectId: event.subjectId,
       actorId: invocation.actorId,
@@ -556,9 +571,10 @@ function initialState(entityType) {
 function isTerminal(status) {
   return ["completed", "failed", "blocked_by_policy", "validation_failed"].includes(status);
 }
-function withoutPrivateHostFields(data) {
-  const { _events: _ignored, ...result } = data;
-  return result;
+function withoutPrivateHostFields(data, eventResultFields) {
+  return Object.fromEntries(
+    Object.entries(data).filter(([key]) => !eventResultFields.includes(key))
+  );
 }
 function errorMessage(error) {
   return error instanceof Error ? error.message : String(error);