@fabricorg/platform-host 2.0.0 → 2.0.1

package/dist/index.d.cts

@@ -382,6 +382,8 @@ interface PlatformHostOptions<TDb> {
         producerModuleVersion(actionId: ActionId, actionVersion: number): string;
         classifyPayload(event: AssetEventEnvelope): EventPayloadClassification;
         traceContext?(event: AssetEventEnvelope): Record<string, string> | undefined;
+        /** Host lifecycle events are excluded by default; opt in only after making their payload audit-safe. */
+        shouldPublish?(event: AssetEventEnvelope): boolean;
     };
     /** Optional vertical-owned evaluator. When absent, agent behavior is unchanged. */
     hitlEvaluator?: AgentActionPolicyEvaluator;
@@ -433,8 +435,15 @@ interface GovernedActionHost {
 
 declare function createGovernedActionHost<TDb>(options: PlatformHostOptions<TDb>): GovernedActionHost;
 
+interface MemoryPlatformHostTransactionProvider<TDb> {
+    snapshot(db: TDb): TDb;
+    restore(db: TDb, snapshot: TDb): void;
+}
 declare class MemoryPlatformHostStore<TDb> implements RecoverablePlatformHostStore<TDb>, ApprovalPlatformHostStore<TDb>, GovernancePlatformHostStore<TDb>, OutboxPlatformHostStore<TDb> {
     readonly db: TDb;
+    readonly transactionalOutbox: boolean;
+    transactionWithEvents?: <TResult>(run: (transaction: PlatformHostMutationTransaction<TDb>) => Promise<TResult>) => Promise<TResult>;
+    private transactionTail;
     readonly invocations: ActionInvocationRecord[];
     readonly policyEvaluations: PolicyEvaluationRecord[];
     readonly adapterInvocations: AdapterInvocationRecord[];
@@ -443,8 +452,9 @@ declare class MemoryPlatformHostStore<TDb> implements RecoverablePlatformHostSto
     readonly executionAttestations: ExecutionAttestationRecord[];
     readonly externalReconciliations: ExternalReconciliationRecord[];
     readonly outbox: OutboxRecord[];
-    constructor(db: TDb);
+    constructor(db: TDb, transactionProvider?: MemoryPlatformHostTransactionProvider<TDb>);
     transaction<TResult>(run: (db: TDb) => Promise<TResult>): Promise<TResult>;
+    private runTransactionWithEvents;
     createActionInvocation(input: CreateActionInvocationInput): Promise<ActionInvocationRecord>;
     getActionInvocation(id: string, tenantId: string, spaceId: string): Promise<ActionInvocationRecord | undefined>;
     updateActionInvocation(id: string, tenantId: string, spaceId: string, patch: Partial<Pick<ActionInvocationRecord, "status" | "result" | "error">>): Promise<void>;
@@ -593,4 +603,4 @@ declare function runPlatformActionWorkerCycle<TDb>(options: PlatformActionWorker
 /** Poll until aborted. Each iteration is bounded and waits without busy-spinning. */
 declare function runPlatformActionWorker<TDb>(options: PlatformActionWorkerOptions<TDb>): Promise<void>;
 
-export { type ActionApprovalDecision, type ActionAuthorizationInput, type ActionExecutionAuthorizationInput, type ActionExecutionReason, type ActionInvocationRecord, type AdapterInvocationRecord, type AdapterInvocationStatus, type ApprovalDecisionTransitionResult, type ApprovalPlatformHostStore, type AtomicMutationPlatformHostStore, type BeginApprovalDecisionInput, type ClaimActionInvocationsInput, type ClaimOutboxInput, type CreateActionInvocationInput, type DispatchActionInput, type DispatchActionResult, type EnterpriseEventEnvelope, type EnterpriseEventPublisher, type EventPayloadClassification, type ExecuteActionResult, type ExecuteInvocationOptions, type ExecutionAttestationRecord, type ExternalReconciliationRecord, type GovernancePlatformHostStore, type GovernedActionHost, type HitlDecisionEvidence, type ListActionInvocationsInput, MemoryPlatformHostStore, type OutboxEventMetadata, type OutboxPlatformHostStore, type OutboxRecord, type OutboxRelayOptions, type OutboxRelayResult, type OutboxStatus, PLATFORM_HOST_CONTRACT_VERSION, type PendingAssetEvent, type PersistedActionApprovalDecision, type PlatformActionDispatcher, type PlatformActionWorkerCycleResult, type PlatformActionWorkerOptions, type PlatformHostAuthorization, type PlatformHostMutationTransaction, type PlatformHostOptions, type PlatformHostSqlClient, type PlatformHostSqlResult, type PlatformHostStore, type PolicyEvaluationRecord, type PolicyObligationRecord, PostgresPlatformHostStore, type PostgresPlatformHostTransactionContext, type PostgresPlatformHostTransactionProvider, type RecoverablePlatformHostStore, type SubmitActionInput, type SubmitActionResult, cloneOutboxRecord, createGovernedActionHost, createStoreBackedActionDispatcher, runOutboxRelayCycle, runPlatformActionWorker, runPlatformActionWorkerCycle, toEnterpriseEventEnvelope };
+export { type ActionApprovalDecision, type ActionAuthorizationInput, type ActionExecutionAuthorizationInput, type ActionExecutionReason, type ActionInvocationRecord, type AdapterInvocationRecord, type AdapterInvocationStatus, type ApprovalDecisionTransitionResult, type ApprovalPlatformHostStore, type AtomicMutationPlatformHostStore, type BeginApprovalDecisionInput, type ClaimActionInvocationsInput, type ClaimOutboxInput, type CreateActionInvocationInput, type DispatchActionInput, type DispatchActionResult, type EnterpriseEventEnvelope, type EnterpriseEventPublisher, type EventPayloadClassification, type ExecuteActionResult, type ExecuteInvocationOptions, type ExecutionAttestationRecord, type ExternalReconciliationRecord, type GovernancePlatformHostStore, type GovernedActionHost, type HitlDecisionEvidence, type ListActionInvocationsInput, MemoryPlatformHostStore, type MemoryPlatformHostTransactionProvider, type OutboxEventMetadata, type OutboxPlatformHostStore, type OutboxRecord, type OutboxRelayOptions, type OutboxRelayResult, type OutboxStatus, PLATFORM_HOST_CONTRACT_VERSION, type PendingAssetEvent, type PersistedActionApprovalDecision, type PlatformActionDispatcher, type PlatformActionWorkerCycleResult, type PlatformActionWorkerOptions, type PlatformHostAuthorization, type PlatformHostMutationTransaction, type PlatformHostOptions, type PlatformHostSqlClient, type PlatformHostSqlResult, type PlatformHostStore, type PolicyEvaluationRecord, type PolicyObligationRecord, PostgresPlatformHostStore, type PostgresPlatformHostTransactionContext, type PostgresPlatformHostTransactionProvider, type RecoverablePlatformHostStore, type SubmitActionInput, type SubmitActionResult, cloneOutboxRecord, createGovernedActionHost, createStoreBackedActionDispatcher, runOutboxRelayCycle, runPlatformActionWorker, runPlatformActionWorkerCycle, toEnterpriseEventEnvelope };

package/dist/index.d.ts

@@ -382,6 +382,8 @@ interface PlatformHostOptions<TDb> {
         producerModuleVersion(actionId: ActionId, actionVersion: number): string;
         classifyPayload(event: AssetEventEnvelope): EventPayloadClassification;
         traceContext?(event: AssetEventEnvelope): Record<string, string> | undefined;
+        /** Host lifecycle events are excluded by default; opt in only after making their payload audit-safe. */
+        shouldPublish?(event: AssetEventEnvelope): boolean;
     };
     /** Optional vertical-owned evaluator. When absent, agent behavior is unchanged. */
     hitlEvaluator?: AgentActionPolicyEvaluator;
@@ -433,8 +435,15 @@ interface GovernedActionHost {
 
 declare function createGovernedActionHost<TDb>(options: PlatformHostOptions<TDb>): GovernedActionHost;
 
+interface MemoryPlatformHostTransactionProvider<TDb> {
+    snapshot(db: TDb): TDb;
+    restore(db: TDb, snapshot: TDb): void;
+}
 declare class MemoryPlatformHostStore<TDb> implements RecoverablePlatformHostStore<TDb>, ApprovalPlatformHostStore<TDb>, GovernancePlatformHostStore<TDb>, OutboxPlatformHostStore<TDb> {
     readonly db: TDb;
+    readonly transactionalOutbox: boolean;
+    transactionWithEvents?: <TResult>(run: (transaction: PlatformHostMutationTransaction<TDb>) => Promise<TResult>) => Promise<TResult>;
+    private transactionTail;
     readonly invocations: ActionInvocationRecord[];
     readonly policyEvaluations: PolicyEvaluationRecord[];
     readonly adapterInvocations: AdapterInvocationRecord[];
@@ -443,8 +452,9 @@ declare class MemoryPlatformHostStore<TDb> implements RecoverablePlatformHostSto
     readonly executionAttestations: ExecutionAttestationRecord[];
     readonly externalReconciliations: ExternalReconciliationRecord[];
     readonly outbox: OutboxRecord[];
-    constructor(db: TDb);
+    constructor(db: TDb, transactionProvider?: MemoryPlatformHostTransactionProvider<TDb>);
     transaction<TResult>(run: (db: TDb) => Promise<TResult>): Promise<TResult>;
+    private runTransactionWithEvents;
     createActionInvocation(input: CreateActionInvocationInput): Promise<ActionInvocationRecord>;
     getActionInvocation(id: string, tenantId: string, spaceId: string): Promise<ActionInvocationRecord | undefined>;
     updateActionInvocation(id: string, tenantId: string, spaceId: string, patch: Partial<Pick<ActionInvocationRecord, "status" | "result" | "error">>): Promise<void>;
@@ -593,4 +603,4 @@ declare function runPlatformActionWorkerCycle<TDb>(options: PlatformActionWorker
 /** Poll until aborted. Each iteration is bounded and waits without busy-spinning. */
 declare function runPlatformActionWorker<TDb>(options: PlatformActionWorkerOptions<TDb>): Promise<void>;
 
-export { type ActionApprovalDecision, type ActionAuthorizationInput, type ActionExecutionAuthorizationInput, type ActionExecutionReason, type ActionInvocationRecord, type AdapterInvocationRecord, type AdapterInvocationStatus, type ApprovalDecisionTransitionResult, type ApprovalPlatformHostStore, type AtomicMutationPlatformHostStore, type BeginApprovalDecisionInput, type ClaimActionInvocationsInput, type ClaimOutboxInput, type CreateActionInvocationInput, type DispatchActionInput, type DispatchActionResult, type EnterpriseEventEnvelope, type EnterpriseEventPublisher, type EventPayloadClassification, type ExecuteActionResult, type ExecuteInvocationOptions, type ExecutionAttestationRecord, type ExternalReconciliationRecord, type GovernancePlatformHostStore, type GovernedActionHost, type HitlDecisionEvidence, type ListActionInvocationsInput, MemoryPlatformHostStore, type OutboxEventMetadata, type OutboxPlatformHostStore, type OutboxRecord, type OutboxRelayOptions, type OutboxRelayResult, type OutboxStatus, PLATFORM_HOST_CONTRACT_VERSION, type PendingAssetEvent, type PersistedActionApprovalDecision, type PlatformActionDispatcher, type PlatformActionWorkerCycleResult, type PlatformActionWorkerOptions, type PlatformHostAuthorization, type PlatformHostMutationTransaction, type PlatformHostOptions, type PlatformHostSqlClient, type PlatformHostSqlResult, type PlatformHostStore, type PolicyEvaluationRecord, type PolicyObligationRecord, PostgresPlatformHostStore, type PostgresPlatformHostTransactionContext, type PostgresPlatformHostTransactionProvider, type RecoverablePlatformHostStore, type SubmitActionInput, type SubmitActionResult, cloneOutboxRecord, createGovernedActionHost, createStoreBackedActionDispatcher, runOutboxRelayCycle, runPlatformActionWorker, runPlatformActionWorkerCycle, toEnterpriseEventEnvelope };
+export { type ActionApprovalDecision, type ActionAuthorizationInput, type ActionExecutionAuthorizationInput, type ActionExecutionReason, type ActionInvocationRecord, type AdapterInvocationRecord, type AdapterInvocationStatus, type ApprovalDecisionTransitionResult, type ApprovalPlatformHostStore, type AtomicMutationPlatformHostStore, type BeginApprovalDecisionInput, type ClaimActionInvocationsInput, type ClaimOutboxInput, type CreateActionInvocationInput, type DispatchActionInput, type DispatchActionResult, type EnterpriseEventEnvelope, type EnterpriseEventPublisher, type EventPayloadClassification, type ExecuteActionResult, type ExecuteInvocationOptions, type ExecutionAttestationRecord, type ExternalReconciliationRecord, type GovernancePlatformHostStore, type GovernedActionHost, type HitlDecisionEvidence, type ListActionInvocationsInput, MemoryPlatformHostStore, type MemoryPlatformHostTransactionProvider, type OutboxEventMetadata, type OutboxPlatformHostStore, type OutboxRecord, type OutboxRelayOptions, type OutboxRelayResult, type OutboxStatus, PLATFORM_HOST_CONTRACT_VERSION, type PendingAssetEvent, type PersistedActionApprovalDecision, type PlatformActionDispatcher, type PlatformActionWorkerCycleResult, type PlatformActionWorkerOptions, type PlatformHostAuthorization, type PlatformHostMutationTransaction, type PlatformHostOptions, type PlatformHostSqlClient, type PlatformHostSqlResult, type PlatformHostStore, type PolicyEvaluationRecord, type PolicyObligationRecord, PostgresPlatformHostStore, type PostgresPlatformHostTransactionContext, type PostgresPlatformHostTransactionProvider, type RecoverablePlatformHostStore, type SubmitActionInput, type SubmitActionResult, cloneOutboxRecord, createGovernedActionHost, createStoreBackedActionDispatcher, runOutboxRelayCycle, runPlatformActionWorker, runPlatformActionWorkerCycle, toEnterpriseEventEnvelope };

package/dist/index.js

@@ -326,6 +326,9 @@ function createGovernedActionHost(options) {
       let domainEvents = [];
       try {
         const runHandler = async (db, transaction) => {
+          if (options.outbox && !transaction?.appendEventWithOutbox) {
+            throw new Error("Outbox egress requires transactionWithEvents to provide appendEventWithOutbox before handler execution.");
+          }
           const handlerResult = action.handler ? await action.handler(
             {
               actionInvocationId,
@@ -692,6 +695,12 @@ function createGovernedActionHost(options) {
       ...invocation.causationId ? { causationId: invocation.causationId } : {}
     };
     if (options.outbox) {
+      const hostLifecycleEvent = (/* @__PURE__ */ new Set(["AdapterInvocationStarted", "AdapterInvocationSucceeded", "AdapterInvocationFailed", "ComplianceBlocked"])).has(envelope.eventType);
+      const shouldPublish = options.outbox.shouldPublish?.(envelope) ?? !hostLifecycleEvent;
+      if (!shouldPublish) {
+        await (transaction ?? options.store).appendEvent(envelope);
+        return;
+      }
       const traceContext = options.outbox.traceContext?.(envelope);
       const metadata = {
         producerModuleVersion: options.outbox.producerModuleVersion(invocation.actionId, invocation.actionVersion),
@@ -847,13 +856,13 @@ async function runOutboxRelayCycle(options) {
         continue;
       }
       result.published += 1;
-    } catch (error) {
+    } catch {
       const deadLetter = record.attemptCount >= maxAttempts;
       try {
         await options.store.markOutboxFailed({
           id: record.id,
           workerId: options.workerId,
-          error: error instanceof Error ? error.message : String(error),
+          error: "Event publisher failed",
           availableAt: new Date(now().getTime() + (options.retryDelayMs?.(record.attemptCount) ?? 1e3)),
           deadLetter
         });
@@ -874,10 +883,14 @@ function cloneOutboxRecord(record) {
 
 // src/memory-store.ts
 var MemoryPlatformHostStore = class {
-  constructor(db) {
+  constructor(db, transactionProvider) {
     this.db = db;
+    this.transactionalOutbox = transactionProvider !== void 0;
+    if (transactionProvider) this.transactionWithEvents = (run) => this.runTransactionWithEvents(run, transactionProvider);
   }
   db;
+  transactionalOutbox;
+  transactionTail = Promise.resolve();
   invocations = [];
   policyEvaluations = [];
   adapterInvocations = [];
@@ -889,6 +902,50 @@ var MemoryPlatformHostStore = class {
   async transaction(run) {
     return run(this.db);
   }
+  async runTransactionWithEvents(run, transactionProvider) {
+    let release;
+    const previous = this.transactionTail;
+    this.transactionTail = new Promise((resolve) => {
+      release = resolve;
+    });
+    await previous;
+    let domainSnapshot;
+    let snapshotCreated = false;
+    try {
+      domainSnapshot = transactionProvider.snapshot(this.db);
+      snapshotCreated = true;
+      const pendingEvents = [];
+      const pendingUpdates = [];
+      const appendPending = async (event, metadata) => {
+        if (this.events.some((candidate) => candidate.id === event.id) || pendingEvents.some((candidate) => candidate.event.id === event.id)) return;
+        pendingEvents.push({ event, ...metadata ? { metadata } : {} });
+      };
+      const result = await run({
+        db: this.db,
+        appendEvent: (event) => appendPending(event),
+        appendEventWithOutbox: (event, metadata) => appendPending(event, metadata),
+        nextEventSequence: async (tenantId, spaceId) => (await this.listEvents(tenantId, spaceId)).length + pendingEvents.filter((candidate) => candidate.event.tenantId === tenantId && candidate.event.spaceId === spaceId).length + 1,
+        listEvents: async (tenantId, spaceId) => [...await this.listEvents(tenantId, spaceId), ...pendingEvents.map((candidate) => candidate.event).filter((event) => event.tenantId === tenantId && event.spaceId === spaceId)],
+        updateActionInvocation: async (id, tenantId, spaceId, patch) => {
+          pendingUpdates.push({ id, tenantId, spaceId, patch });
+        }
+      });
+      for (const update of pendingUpdates) {
+        if (!await this.getActionInvocation(update.id, update.tenantId, update.spaceId)) throw new Error(`ActionInvocation not found: ${update.id}`);
+      }
+      for (const pending of pendingEvents) {
+        if (pending.metadata) await this.appendEventWithOutbox(pending.event, pending.metadata);
+        else await this.appendEvent(pending.event);
+      }
+      for (const update of pendingUpdates) await this.updateActionInvocation(update.id, update.tenantId, update.spaceId, update.patch);
+      return result;
+    } catch (error) {
+      if (snapshotCreated) transactionProvider.restore(this.db, domainSnapshot);
+      throw error;
+    } finally {
+      release();
+    }
+  }
   async createActionInvocation(input) {
     if (input.idempotencyKey) {
       const existing = this.invocations.find(