@fabricorg/platform-host 2.0.0 → 2.0.1

package/CHANGELOG.md

@@ -1,9 +1,28 @@
 # @fabricorg/platform-host
 
+## 2.0.1
+
+### Patch Changes
+
+- Close final uplift audit gaps: align Host 2.x documentation and migration evidence, surface every
+  compiler/generator API to LLM consumers, make memory outbox egress directly usable, sanitize relay
+  failures, validate complete archetype state maps, support recursive JSON Schema generation, reject
+  cross-platform path traversal, synchronize artifact version stamps, and include package licenses.
+- Require explicit domain snapshot/restore support before memory stores advertise atomic outbox
+  transactions, buffer Host lifecycle commits until success, fail missing transaction capabilities
+  before handlers run, sanitize relay failures, and exclude sensitive Host lifecycle events from bus
+  egress by default.
+- Prevalidate buffered memory transactions so failed commits cannot append partial event or outbox rows.
+- Qualify result-validation rollback documentation by the configured domain transaction provider.
+- Updated dependencies
+  - @fabricorg/platform@0.11.1
+
 ## 2.0.0
 
-### Minor Changes
+### Major Changes
 
+- Require `@fabricorg/platform@^0.11.0` and its manifest v2/result-schema contract. Applications
+  upgrading from Host 1.x must upgrade Platform in the same deployment and regenerate manifest consumers.
 - Add the optional durable event outbox, PostgreSQL and memory adapters, and at-least-once relay.
 - Add manifest v2 typed entity contracts, v1 reader normalization, optional action result schemas, and
   Host enforcement of result validation before events and adapters.
@@ -14,13 +33,6 @@
 - Updated dependencies
   - @fabricorg/platform@0.11.0
 
-## Unreleased
-
-- Validate optional action result schemas immediately after handler execution and before events or
-  adapters. Invalid results roll back the handler transaction and persist a sanitized failure.
-- Add optional memory and PostgreSQL outbox capabilities with atomic canonical-event records,
-  lease-based at-least-once relay, retry, replay, and dead-letter state.
-
 ## 1.0.0
 
 ### Minor Changes

package/README.md

@@ -3,7 +3,7 @@
 The canonical host for the `@fabricorg/platform` mutation pipeline.
 
 ```bash
-pnpm add @fabricorg/platform@^0.10.0 @fabricorg/platform-host@^1.0.0
+pnpm add @fabricorg/platform@^0.11.0 @fabricorg/platform-host@^2.0.0
 ```
 
 ## AI agent integration boundary
@@ -15,7 +15,7 @@ registration, and submit stable idempotent commands. The gateway derives tenant
 calls `submitAction()`; an agent must never call handlers, adapters, workflow internals, or database
 writes directly.
 
-See the [Platform Host 1.0 agent integration
+See the [Platform Host 2.x agent integration
 guide](https://platform.fabric.pro/docs/platform/reference/platform-host) for application wiring,
 execution-time authorization, the PostgreSQL transaction binder, recovery semantics, and the external
 gateway contract.
@@ -101,10 +101,11 @@ Stores without this additive capability retain the legacy boundary for compatibi
 claim atomic domain-write/event persistence.
 
 Actions can optionally declare `resultSchema`. The Host validates public handler result data after
-the handler and before canonical event append or adapter execution. Invalid results roll back the
-handler transaction, emit no domain/completion event, invoke no adapter, and persist only a sanitized
-validation failure. This validates the handler result contract; it does not observe arbitrary writes
-through an application-owned `TDb`.
+the handler and before canonical event append or adapter execution. Invalid results fail the invocation,
+emit no domain/completion event, invoke no adapter, and persist only a sanitized validation failure.
+Domain writes roll back only when the configured store transaction provider includes those writes.
+This validates the handler result contract; it does not observe arbitrary writes through an
+application-owned `TDb`.
 
 ## Agent HITL
 
@@ -177,7 +178,7 @@ explain which contract and provider adapter governed a mutation after dependenci
 const host = createGovernedActionHost({
   // ...
   runtimeEvidence: {
-    hostPackageVersion: "1.0.0",
+    hostPackageVersion: "2.0.1",
     policyRulesetVersion: "gtm-rules.v8",
     providerBridge: { name: "@fabric-harness/databricks", version: "1" },
   },
@@ -196,3 +197,11 @@ the proven event transaction. `runOutboxRelayCycle()` leases and publishes recor
 and dead-letter handling. Delivery is at least once: consumers deduplicate on immutable
 `eventId`. Payload classification is metadata, not a redaction mechanism; event payloads must
 already be audit-safe.
+
+Adapter and compliance lifecycle events remain canonical but are excluded from bus egress by default.
+Use `shouldPublish` to opt them in only when the application has made their payloads safe for that bus.
+
+For deterministic local tests, `MemoryPlatformHostStore` enables governed Host outbox egress only
+when its constructor receives a `MemoryPlatformHostTransactionProvider` with domain `snapshot` and
+`restore` functions. Without that explicit rollback seam, `transactionalOutbox` is false and Host
+construction rejects outbox configuration. PostgreSQL remains the production implementation.

package/dist/index.cjs

@@ -328,6 +328,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,
@@ -694,6 +697,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),
@@ -849,13 +858,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
         });
@@ -876,10 +885,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 = [];
@@ -891,6 +904,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(