@fabricorg/platform-host 1.0.0 → 2.0.1

package/dist/index.js

@@ -14,6 +14,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 AdapterRegistry();
   for (const adapter of options.adapters ?? []) adapters.register(adapter);
   const now = options.now ?? (() => /* @__PURE__ */ new Date());
@@ -320,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,
@@ -338,6 +347,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)
@@ -678,7 +694,30 @@ function createGovernedActionHost(options) {
       correlationId: invocation.correlationId,
       ...invocation.causationId ? { causationId: invocation.causationId } : {}
     };
-    await (transaction ?? options.store).appendEvent(envelope);
+    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),
+        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(
@@ -715,6 +754,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;
@@ -771,12 +814,83 @@ 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 {
+      const deadLetter = record.attemptCount >= maxAttempts;
+      try {
+        await options.store.markOutboxFailed({
+          id: record.id,
+          workerId: options.workerId,
+          error: "Event publisher failed",
+          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) {
+  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 = [];
@@ -784,9 +898,54 @@ var MemoryPlatformHostStore = class {
   policyObligations = [];
   executionAttestations = [];
   externalReconciliations = [];
+  outbox = [];
   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(
@@ -902,6 +1061,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;
   }
@@ -945,12 +1151,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)
@@ -961,6 +1169,7 @@ var PostgresPlatformHostStore = class _PostgresPlatformHostStore {
   db;
   sql;
   transactionWithEvents;
+  transactionalOutbox;
   async ensureSchema() {
     await this.sql.query(`
 			CREATE SCHEMA IF NOT EXISTS fabric_platform;
@@ -1044,6 +1253,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) {
@@ -1326,6 +1544,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)
@@ -1514,6 +1812,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;
@@ -1583,6 +1916,6 @@ async function abortableDelay(milliseconds, signal) {
   });
 }
 
-export { MemoryPlatformHostStore, PLATFORM_HOST_CONTRACT_VERSION, PostgresPlatformHostStore, createGovernedActionHost, createStoreBackedActionDispatcher, runPlatformActionWorker, runPlatformActionWorkerCycle };
+export { MemoryPlatformHostStore, PLATFORM_HOST_CONTRACT_VERSION, PostgresPlatformHostStore, cloneOutboxRecord, createGovernedActionHost, createStoreBackedActionDispatcher, runOutboxRelayCycle, runPlatformActionWorker, runPlatformActionWorkerCycle, toEnterpriseEventEnvelope };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map