@fabricorg/platform-host 1.0.0 → 2.0.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @fabricorg/platform-host
 
+## 2.0.0
+
+### Minor Changes
+
+- 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.
+
+### Patch Changes
+
+- Updated dependencies
+- 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.9.0 @fabricorg/platform-host@^0.7.0
+pnpm add @fabricorg/platform@^0.10.0 @fabricorg/platform-host@^1.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 0.7 agent integration
+See the [Platform Host 1.0 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.
@@ -100,6 +100,12 @@ application knows how its `TDb` is rebound to the transaction's SQL client.
 Stores without this additive capability retain the legacy boundary for compatibility and must not
 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`.
+
 ## Agent HITL
 
 Hosts can inject a vertical-owned `hitlEvaluator`. It runs only for `actorType: "agent"`, after schema
@@ -171,7 +177,7 @@ explain which contract and provider adapter governed a mutation after dependenci
 const host = createGovernedActionHost({
   // ...
   runtimeEvidence: {
-    hostPackageVersion: "0.7.0",
+    hostPackageVersion: "1.0.0",
     policyRulesetVersion: "gtm-rules.v8",
     providerBridge: { name: "@fabric-harness/databricks", version: "1" },
   },
@@ -181,3 +187,12 @@ const host = createGovernedActionHost({
 `MemoryPlatformHostStore` is for tests and local demos. Production control planes use
 `PostgresPlatformHostStore` with Databricks Lakebase (or standard Postgres), call
 `ensureSchema()` at startup, and hydrate projections from `listEvents()`.
+
+## Durable outbox egress
+
+Configure `outbox` on `createGovernedActionHost()` only with an `OutboxPlatformHostStore`.
+The Host then uses `appendEventWithOutbox` so the canonical event and delivery record share
+the proven event transaction. `runOutboxRelayCycle()` leases and publishes records with retry
+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.

package/dist/index.cjs

@@ -16,6 +16,12 @@ var RecoverableFinalizationError = class extends Error {
   name = "RecoverableFinalizationError";
 };
 function createGovernedActionHost(options) {
+  if (options.outbox) {
+    const outboxStore = asOutboxStore(options.store);
+    if (!outboxStore || !asAtomicMutationStore(options.store) || outboxStore.transactionalOutbox !== true) {
+      throw new Error("Outbox egress requires a store with transactionalOutbox and transactionWithEvents capabilities.");
+    }
+  }
   const adapters = new platform.AdapterRegistry();
   for (const adapter of options.adapters ?? []) adapters.register(adapter);
   const now = options.now ?? (() => /* @__PURE__ */ new Date());
@@ -340,6 +346,13 @@ function createGovernedActionHost(options) {
             throw new Error(handlerResult.error ?? "Action handler failed");
           }
           const handlerData = handlerResult.data ?? {};
+          if (action.resultSchema) {
+            const publicResult = withoutPrivateHostFields(handlerData, eventResultFields);
+            const parsedResult = action.resultSchema.safeParse(publicResult);
+            if (!parsedResult.success) {
+              throw new Error(`Action result validation failed at ${parsedResult.error.issues.map((issue) => issue.path.map(String).join(".") || "result").join(", ")}`);
+            }
+          }
           const events = extractEvents(handlerData);
           const undeclaredEvent = events.find(
             (event) => !action.emitsEvents.includes(event.eventType)
@@ -680,7 +693,24 @@ function createGovernedActionHost(options) {
       correlationId: invocation.correlationId,
       ...invocation.causationId ? { causationId: invocation.causationId } : {}
     };
-    await (transaction ?? options.store).appendEvent(envelope);
+    if (options.outbox) {
+      const traceContext = options.outbox.traceContext?.(envelope);
+      const metadata = {
+        producerModuleVersion: options.outbox.producerModuleVersion(invocation.actionId, invocation.actionVersion),
+        payloadClassification: options.outbox.classifyPayload(envelope),
+        ...traceContext ? { traceContext } : {}
+      };
+      if (transaction) {
+        if (!transaction.appendEventWithOutbox) throw new Error("Outbox egress requires an atomic transaction with appendEventWithOutbox.");
+        await transaction.appendEventWithOutbox(envelope, metadata);
+      } else {
+        const outboxStore = asOutboxStore(options.store);
+        if (!outboxStore) throw new Error("Outbox egress requires an outbox-capable Platform Host store.");
+        await outboxStore.appendEventWithOutbox(envelope, metadata);
+      }
+    } else {
+      await (transaction ?? options.store).appendEvent(envelope);
+    }
   }
   async function fail(invocation, status, error) {
     await options.store.updateActionInvocation(
@@ -717,6 +747,10 @@ function asAtomicMutationStore(store) {
   const candidate = store;
   return typeof candidate.transactionWithEvents === "function" ? store : void 0;
 }
+function asOutboxStore(store) {
+  const candidate = store;
+  return typeof candidate.appendEventWithOutbox === "function" && typeof candidate.claimOutbox === "function" ? store : void 0;
+}
 function asGovernanceStore(store) {
   const candidate = store;
   return typeof candidate.recordMutationGovernance === "function" && typeof candidate.appendPolicyObligations === "function" && typeof candidate.appendExecutionAttestation === "function" ? store : void 0;
@@ -773,6 +807,73 @@ function lifecycleId(prefix, invocationId, key) {
   return `${prefix}_${invocationId}_${safeKey}`;
 }
 
+// src/outbox.ts
+function toEnterpriseEventEnvelope(event, metadata) {
+  return {
+    eventId: event.id,
+    eventType: event.eventType,
+    eventSchemaVersion: event.eventSchemaVersion,
+    tenantId: event.tenantId,
+    spaceId: event.spaceId,
+    subjectType: event.subjectType,
+    subjectId: event.subjectId,
+    sequence: event.sequence,
+    ...event.actionInvocationId ? { actionInvocationId: event.actionInvocationId } : {},
+    correlationId: event.correlationId,
+    ...event.causationId ? { causationId: event.causationId } : {},
+    occurredAt: event.occurredAt,
+    recordedAt: event.recordedAt,
+    producerModuleVersion: metadata.producerModuleVersion,
+    payloadClassification: metadata.payloadClassification,
+    ...metadata.traceContext ? { traceContext: { ...metadata.traceContext } } : {},
+    payload: event.payload
+  };
+}
+async function runOutboxRelayCycle(options) {
+  const now = options.now ?? (() => /* @__PURE__ */ new Date());
+  const maxAttempts = options.maxAttempts ?? 10;
+  const records = await options.store.claimOutbox({
+    workerId: options.workerId,
+    leaseDurationMs: options.leaseDurationMs ?? 3e4,
+    limit: options.batchSize ?? 100,
+    now: now()
+  });
+  const result = { claimed: records.length, published: 0, failed: 0, deadLettered: 0 };
+  for (const record of records) {
+    try {
+      await options.publisher.publish(record.event);
+      try {
+        await options.store.markOutboxPublished(record.id, options.workerId, now());
+      } catch {
+        result.failed += 1;
+        continue;
+      }
+      result.published += 1;
+    } catch (error) {
+      const deadLetter = record.attemptCount >= maxAttempts;
+      try {
+        await options.store.markOutboxFailed({
+          id: record.id,
+          workerId: options.workerId,
+          error: error instanceof Error ? error.message : String(error),
+          availableAt: new Date(now().getTime() + (options.retryDelayMs?.(record.attemptCount) ?? 1e3)),
+          deadLetter
+        });
+      } catch {
+      }
+      result.failed += 1;
+      if (deadLetter) result.deadLettered += 1;
+    }
+  }
+  return result;
+}
+function cloneOutboxRecord(record) {
+  return {
+    ...record,
+    event: { ...record.event, ...record.event.traceContext ? { traceContext: { ...record.event.traceContext } } : {} }
+  };
+}
+
 // src/memory-store.ts
 var MemoryPlatformHostStore = class {
   constructor(db) {
@@ -786,6 +887,7 @@ var MemoryPlatformHostStore = class {
   policyObligations = [];
   executionAttestations = [];
   externalReconciliations = [];
+  outbox = [];
   async transaction(run) {
     return run(this.db);
   }
@@ -904,6 +1006,53 @@ var MemoryPlatformHostStore = class {
     if (this.events.some((candidate) => candidate.id === event.id)) return;
     this.events.push(event);
   }
+  async appendEventWithOutbox(event, metadata) {
+    if (this.events.some((candidate) => candidate.id === event.id)) return;
+    const createdAt = new Date(event.recordedAt);
+    this.events.push(event);
+    this.outbox.push({
+      id: event.id,
+      tenantId: event.tenantId,
+      spaceId: event.spaceId,
+      event: toEnterpriseEventEnvelope(event, metadata),
+      status: "pending",
+      attemptCount: 0,
+      availableAt: createdAt,
+      createdAt
+    });
+  }
+  async claimOutbox(input) {
+    const current = input.now ?? /* @__PURE__ */ new Date();
+    return this.outbox.filter((record) => record.status === "pending" && record.availableAt <= current && (!record.leaseExpiresAt || record.leaseExpiresAt <= current) && (!input.tenantId || record.tenantId === input.tenantId) && (!input.spaceId || record.spaceId === input.spaceId)).sort((left, right) => left.createdAt.getTime() - right.createdAt.getTime() || left.id.localeCompare(right.id)).slice(0, Math.max(1, Math.min(input.limit ?? 100, 1e3))).map((record) => {
+      record.leaseOwner = input.workerId;
+      record.leaseExpiresAt = new Date(current.getTime() + input.leaseDurationMs);
+      record.attemptCount += 1;
+      return cloneOutboxRecord(record);
+    });
+  }
+  async markOutboxPublished(id, workerId, publishedAt) {
+    const record = this.requireLeasedOutbox(id, workerId);
+    record.status = "published";
+    record.publishedAt = publishedAt;
+    delete record.leaseOwner;
+    delete record.leaseExpiresAt;
+  }
+  async markOutboxFailed(input) {
+    const record = this.requireLeasedOutbox(input.id, input.workerId);
+    record.status = input.deadLetter ? "dead_letter" : "pending";
+    record.lastError = input.error;
+    record.availableAt = input.availableAt;
+    delete record.leaseOwner;
+    delete record.leaseExpiresAt;
+  }
+  async listOutbox(input = {}) {
+    return this.outbox.filter((record) => (!input.tenantId || record.tenantId === input.tenantId) && (!input.spaceId || record.spaceId === input.spaceId) && (!input.statuses?.length || input.statuses.includes(record.status))).map(cloneOutboxRecord);
+  }
+  requireLeasedOutbox(id, workerId) {
+    const record = this.outbox.find((candidate) => candidate.id === id);
+    if (!record || record.leaseOwner !== workerId) throw new Error(`Outbox record ${id} is not leased by ${workerId}.`);
+    return record;
+  }
   async nextEventSequence(tenantId, spaceId) {
     return this.events.filter((event) => event.tenantId === tenantId && event.spaceId === spaceId).length + 1;
   }
@@ -947,12 +1096,14 @@ var PostgresPlatformHostStore = class _PostgresPlatformHostStore {
   constructor(db, sql, transactionProvider) {
     this.db = db;
     this.sql = sql;
+    this.transactionalOutbox = transactionProvider !== void 0;
     if (transactionProvider) {
       this.transactionWithEvents = async (run) => transactionProvider.run(async ({ db: db2, sql: sql2 }) => {
         const scoped = new _PostgresPlatformHostStore(db2, sql2);
         return run({
           db: db2,
           appendEvent: (event) => scoped.appendEvent(event),
+          appendEventWithOutbox: (event, metadata) => scoped.appendEventWithOutbox(event, metadata),
           nextEventSequence: (tenantId, spaceId) => scoped.nextEventSequence(tenantId, spaceId),
           listEvents: (tenantId, spaceId) => scoped.listEvents(tenantId, spaceId),
           updateActionInvocation: (id, tenantId, spaceId, patch) => scoped.updateActionInvocation(id, tenantId, spaceId, patch)
@@ -963,6 +1114,7 @@ var PostgresPlatformHostStore = class _PostgresPlatformHostStore {
   db;
   sql;
   transactionWithEvents;
+  transactionalOutbox;
   async ensureSchema() {
     await this.sql.query(`
 			CREATE SCHEMA IF NOT EXISTS fabric_platform;
@@ -1046,6 +1198,15 @@ var PostgresPlatformHostStore = class _PostgresPlatformHostStore {
 			CREATE INDEX IF NOT EXISTS asset_events_subject_idx
 				ON fabric_platform.asset_events
 				(tenant_id, space_id, subject_type, subject_id, sequence);
+			CREATE TABLE IF NOT EXISTS fabric_platform.event_outbox (
+				id text PRIMARY KEY, tenant_id text NOT NULL, space_id text NOT NULL,
+				event jsonb NOT NULL, status text NOT NULL DEFAULT 'pending',
+				attempt_count integer NOT NULL DEFAULT 0, available_at timestamptz NOT NULL,
+				lease_owner text, lease_expires_at timestamptz, last_error text,
+				created_at timestamptz NOT NULL, published_at timestamptz
+			);
+			CREATE INDEX IF NOT EXISTS event_outbox_claim_idx
+				ON fabric_platform.event_outbox (status, available_at, lease_expires_at, created_at);
 		`);
   }
   async transaction(run) {
@@ -1328,6 +1489,86 @@ var PostgresPlatformHostStore = class _PostgresPlatformHostStore {
       ]
     );
   }
+  async appendEventWithOutbox(event, metadata) {
+    const envelope = toEnterpriseEventEnvelope(event, metadata);
+    await this.sql.query(
+      `WITH inserted_event AS (
+				INSERT INTO fabric_platform.asset_events
+				 (id,tenant_id,space_id,event_type,event_schema_version,subject_type,subject_id,
+				  actor_id,actor_type,action_invocation_id,payload,sequence,occurred_at,recorded_at,
+				  correlation_id,causation_id)
+				 VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11::jsonb,$12,$13,$14,$15,$16)
+				 ON CONFLICT (id) DO NOTHING RETURNING id
+			)
+			INSERT INTO fabric_platform.event_outbox
+			 (id,tenant_id,space_id,event,status,attempt_count,available_at,created_at)
+			SELECT $1,$2,$3,$17::jsonb,'pending',0,$14,$14 FROM inserted_event
+			ON CONFLICT (id) DO NOTHING`,
+      [
+        event.id,
+        event.tenantId,
+        event.spaceId,
+        event.eventType,
+        event.eventSchemaVersion,
+        event.subjectType,
+        event.subjectId,
+        event.actorId,
+        event.actorType,
+        event.actionInvocationId ?? null,
+        JSON.stringify(event.payload),
+        event.sequence,
+        event.occurredAt,
+        event.recordedAt,
+        event.correlationId,
+        event.causationId ?? null,
+        JSON.stringify(envelope)
+      ]
+    );
+  }
+  async claimOutbox(input) {
+    const current = input.now ?? /* @__PURE__ */ new Date();
+    const leaseExpiresAt = new Date(current.getTime() + input.leaseDurationMs);
+    const result = await this.sql.query(
+      `WITH claimable AS (
+				SELECT id FROM fabric_platform.event_outbox
+				WHERE status='pending' AND available_at <= $1
+				  AND (lease_expires_at IS NULL OR lease_expires_at <= $1)
+				  AND ($2::text IS NULL OR tenant_id=$2)
+				  AND ($3::text IS NULL OR space_id=$3)
+				ORDER BY created_at,id FOR UPDATE SKIP LOCKED LIMIT $4
+			)
+			UPDATE fabric_platform.event_outbox AS item
+			SET lease_owner=$5, lease_expires_at=$6, attempt_count=attempt_count+1
+			FROM claimable WHERE item.id=claimable.id RETURNING item.*`,
+      [current, input.tenantId ?? null, input.spaceId ?? null, Math.max(1, Math.min(input.limit ?? 100, 1e3)), input.workerId, leaseExpiresAt]
+    );
+    return result.rows.map(toOutboxRecord);
+  }
+  async markOutboxPublished(id, workerId, publishedAt) {
+    const result = await this.sql.query(
+      `UPDATE fabric_platform.event_outbox SET status='published',published_at=$3,
+			 lease_owner=NULL,lease_expires_at=NULL WHERE id=$1 AND lease_owner=$2 RETURNING id`,
+      [id, workerId, publishedAt]
+    );
+    if (result.rows.length === 0) throw new Error(`Outbox record ${id} is not leased by ${workerId}.`);
+  }
+  async markOutboxFailed(input) {
+    const result = await this.sql.query(
+      `UPDATE fabric_platform.event_outbox SET status=$3,last_error=$4,available_at=$5,
+			 lease_owner=NULL,lease_expires_at=NULL WHERE id=$1 AND lease_owner=$2 RETURNING id`,
+      [input.id, input.workerId, input.deadLetter ? "dead_letter" : "pending", input.error, input.availableAt]
+    );
+    if (result.rows.length === 0) throw new Error(`Outbox record ${input.id} is not leased by ${input.workerId}.`);
+  }
+  async listOutbox(input = {}) {
+    const result = await this.sql.query(
+      `SELECT * FROM fabric_platform.event_outbox
+			 WHERE ($1::text IS NULL OR tenant_id=$1) AND ($2::text IS NULL OR space_id=$2)
+			 AND ($3::text[] IS NULL OR status=ANY($3::text[])) ORDER BY created_at,id`,
+      [input.tenantId ?? null, input.spaceId ?? null, input.statuses?.length ? input.statuses : null]
+    );
+    return result.rows.map(toOutboxRecord);
+  }
   async nextEventSequence(tenantId, spaceId) {
     const result = await this.sql.query(
       `INSERT INTO fabric_platform.event_sequences (tenant_id,space_id,next_sequence)
@@ -1516,6 +1757,41 @@ function toEventRecord(row) {
     ...row.causation_id ? { causationId: String(row.causation_id) } : {}
   };
 }
+function toOutboxRecord(row) {
+  const event = row.event;
+  return {
+    id: String(row.id),
+    tenantId: String(row.tenant_id),
+    spaceId: String(row.space_id),
+    event: {
+      eventId: String(event.eventId),
+      eventType: String(event.eventType),
+      eventSchemaVersion: Number(event.eventSchemaVersion),
+      tenantId: String(event.tenantId),
+      spaceId: String(event.spaceId),
+      subjectType: String(event.subjectType),
+      subjectId: String(event.subjectId),
+      sequence: Number(event.sequence),
+      ...event.actionInvocationId ? { actionInvocationId: String(event.actionInvocationId) } : {},
+      correlationId: String(event.correlationId),
+      ...event.causationId ? { causationId: String(event.causationId) } : {},
+      occurredAt: new Date(event.occurredAt),
+      recordedAt: new Date(event.recordedAt),
+      producerModuleVersion: String(event.producerModuleVersion),
+      payloadClassification: String(event.payloadClassification),
+      ...event.traceContext ? { traceContext: event.traceContext } : {},
+      payload: event.payload
+    },
+    status: String(row.status),
+    attemptCount: Number(row.attempt_count),
+    availableAt: new Date(row.available_at),
+    ...row.lease_owner ? { leaseOwner: String(row.lease_owner) } : {},
+    ...row.lease_expires_at ? { leaseExpiresAt: new Date(row.lease_expires_at) } : {},
+    ...row.last_error ? { lastError: String(row.last_error) } : {},
+    createdAt: new Date(row.created_at),
+    ...row.published_at ? { publishedAt: new Date(row.published_at) } : {}
+  };
+}
 
 // src/worker.ts
 var DEFAULT_BATCH_SIZE = 10;
@@ -1588,9 +1864,12 @@ async function abortableDelay(milliseconds, signal) {
 exports.MemoryPlatformHostStore = MemoryPlatformHostStore;
 exports.PLATFORM_HOST_CONTRACT_VERSION = PLATFORM_HOST_CONTRACT_VERSION;
 exports.PostgresPlatformHostStore = PostgresPlatformHostStore;
+exports.cloneOutboxRecord = cloneOutboxRecord;
 exports.createGovernedActionHost = createGovernedActionHost;
 exports.createStoreBackedActionDispatcher = createStoreBackedActionDispatcher;
+exports.runOutboxRelayCycle = runOutboxRelayCycle;
 exports.runPlatformActionWorker = runPlatformActionWorker;
 exports.runPlatformActionWorkerCycle = runPlatformActionWorkerCycle;
+exports.toEnterpriseEventEnvelope = toEnterpriseEventEnvelope;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map