@pattern-stack/codegen 0.22.0 → 0.24.0

package/dist/runtime/subsystems/integration/integration-change-emitter.protocol.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Integration subsystem — change-emitter protocol (port).
+ *
+ * `IIntegrationChangeEmitter` is the OPT-IN seam through which the generic
+ * orchestrator (`ExecuteIntegrationUseCase`) publishes a typed, data-level
+ * domain event after every sink write/soft-delete. It is the upstream-generalized
+ * form of the per-sink event emission swe-brain hand-built (ADR-0009 Amendment B):
+ * the differ already records `changed_fields` on `integration_run_items`, but
+ * nothing publishes a "this entity changed" domain event for downstream
+ * trigger→action consumers. This port closes that gap.
+ *
+ * ## Why a port (not a direct TypedEventBus call in the orchestrator)
+ *
+ * The orchestrator is strictly provider- AND entity-agnostic: `entityType` is a
+ * bare `string` and the canonical record is generic `T` (see the use-case header
+ * "No CRM bleed"). It therefore cannot know the typed event NAME
+ * (`<entity>_created`) or the typed payload shape at compile time. The typed
+ * knowledge lives at the per-entity assembly wiring (codegen knows the entity
+ * name there). So the orchestrator depends on this thin, untyped port; codegen
+ * binds a per-entity adapter that maps `(operation) → <entity>_<verb>` and calls
+ * the project's generated `TypedEventBus.publish(...)` with the typed payload.
+ *
+ * ## Backwards compatibility
+ *
+ * The port is `@Optional()` on the orchestrator. Entities that do NOT opt in
+ * (`integration.sink.emit_changes` absent/false) bind no emitter, so the
+ * orchestrator's `this.emitter` is `undefined` and NOTHING is published — zero
+ * behavior change. This is the invariant the snapshot fixture (which opts none
+ * in) keeps green.
+ *
+ * ## Provenance — loop-breaking
+ *
+ * Every emitted event carries `source: 'integration'` in its payload. A future
+ * write-back action (the Intervention layer in swe-brain terms) that subscribes
+ * to these events can detect `source === 'integration'` and decline to echo the
+ * change back to the vendor, breaking the inbound→writeback→inbound loop. This
+ * is the data-layer counterpart of the loopback middleware that already guards
+ * the read side (`createLoopbackMiddleware`).
+ *
+ * ## Transactionality
+ *
+ * `emitChange` receives the same `tx` the sink wrote under (when the sink exposes
+ * one — today the sink owns its own transaction internally, so `tx` is reserved
+ * for the future where the orchestrator drives the transaction). The generated
+ * adapter forwards `tx` into `TypedEventBus.publish(type, id, payload, { tx })`,
+ * so the event lands in the outbox iff the row commits (the events subsystem's
+ * outbox guarantee). When `tx` is absent the publish is post-commit best-effort,
+ * matching today's sink-owns-its-own-transaction reality.
+ */
+/** The data-level action the orchestrator observed. Maps onto the generated
+ *  event verb: `created → <entity>_created`, `updated → <entity>_edited`
+ *  (per swe-brain ADR-0009 B1 — `_edited`, never `_updated`),
+ *  `deleted → <entity>_deleted` (tombstone soft-delete). `noop` never emits. */
+type IntegrationChangeAction = 'created' | 'updated' | 'deleted';
+/**
+ * The vendor-blind change descriptor the orchestrator hands the emitter. The
+ * generated adapter reshapes this into the typed `<entity>_<verb>` payload
+ * (`{ entityId, externalId, provider, changedFields?, source: 'integration' }`).
+ */
+interface IntegrationChangeNotification {
+    /** The local row id the sink wrote/soft-deleted (the domain aggregate id —
+     *  becomes `aggregateId` on the published event AND `entityId` in the payload). */
+    readonly entityId: string;
+    /** Vendor-prefixed-or-bare external id the change keyed on (e.g. `slack:123`). */
+    readonly externalId: string;
+    /** Provider label from `ExecuteIntegrationInput.provider` (e.g. `'slack'`). */
+    readonly provider: string;
+    /** The observed action. `created`/`updated` come from the existing-row check;
+     *  `deleted` from the soft-delete path. */
+    readonly action: IntegrationChangeAction;
+    /** The differ's structured per-field before/after map (the same value written
+     *  to `integration_run_items.changed_fields`). Absent on deletes. */
+    readonly changedFields?: Record<string, unknown>;
+    /** Multi-tenant deployments thread the tenant id through to the event metadata. */
+    readonly tenantId?: string | null;
+    /** The transaction the sink wrote under, when the orchestrator drives one.
+     *  Forwarded to `TypedEventBus.publish(..., { tx })` for the outbox guarantee.
+     *  Reserved: today the sink owns its own transaction, so this is usually
+     *  `undefined` and the publish is post-commit. Typed `unknown` here so the
+     *  port stays free of a Drizzle type dependency (the generated adapter narrows). */
+    readonly tx?: unknown;
+}
+/**
+ * Post-upsert change-event emission port.
+ *
+ * One implementation per opted-in (entity, provider) assembly — codegen-emitted,
+ * bound to `INTEGRATION_CHANGE_EMITTER` in that assembly module. The orchestrator
+ * injects it `@Optional()`; an unbound token means no emission (back-compat).
+ */
+interface IIntegrationChangeEmitter {
+    /**
+     * Publish the typed `<entity>_<verb>` domain event for one observed change.
+     *
+     * MUST be called only for real changes — the orchestrator never calls this on
+     * a `noop` diff (canonical state unchanged) or a delete that hit no local row
+     * (no tombstone created). Implementations should treat a call as "this thing
+     * happened" and publish unconditionally.
+     *
+     * Errors are the orchestrator's concern: it wraps the call so a failed publish
+     * does not abort the run (the row is already written; emission is best-effort
+     * unless ridden on the outbox tx). See `ExecuteIntegrationUseCase.processChange`.
+     */
+    emitChange(notification: IntegrationChangeNotification): Promise<void>;
+}
+
+export type { IIntegrationChangeEmitter, IntegrationChangeAction, IntegrationChangeNotification };

package/dist/runtime/subsystems/integration/integration-change-emitter.protocol.js

@@ -0,0 +1 @@
+//# sourceMappingURL=integration-change-emitter.protocol.js.map

package/dist/runtime/subsystems/integration/integration-change-emitter.protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/runtime/subsystems/integration/integration-cursor-store.drizzle-backend.js

@@ -1,8 +1,8 @@
 import {
   PostgresCursorStore
-} from "../../../chunk-O2A6XHGD.js";
+} from "../../../chunk-LLDJS7PJ.js";
 import "../../../chunk-HNWZFNKP.js";
-import "../../../chunk-S7C6TIIF.js";
+import "../../../chunk-S5G3HO7N.js";
 import "../../../chunk-MZ6GV4YF.js";
 import "../../../chunk-U64T4YZE.js";
 import "../../../chunk-2E224ZSN.js";

package/dist/runtime/subsystems/integration/integration-run-recorder.drizzle-backend.js

@@ -1,9 +1,9 @@
 import {
   DrizzleIntegrationRunRecorder
-} from "../../../chunk-FFUDEIFF.js";
+} from "../../../chunk-HN5HT5WL.js";
 import "../../../chunk-HNWZFNKP.js";
 import "../../../chunk-SQDOBLBP.js";
-import "../../../chunk-S7C6TIIF.js";
+import "../../../chunk-S5G3HO7N.js";
 import "../../../chunk-MZ6GV4YF.js";
 import "../../../chunk-U64T4YZE.js";
 import "../../../chunk-2E224ZSN.js";

package/dist/runtime/subsystems/integration/integration.module.js

@@ -1,14 +1,14 @@
 import {
   IntegrationModule
-} from "../../../chunk-QFUIE37H.js";
-import "../../../chunk-FFUDEIFF.js";
+} from "../../../chunk-KFXXOFDC.js";
+import "../../../chunk-HN5HT5WL.js";
 import "../../../chunk-EO2QPOKH.js";
-import "../../../chunk-O2A6XHGD.js";
+import "../../../chunk-LLDJS7PJ.js";
 import "../../../chunk-HNWZFNKP.js";
 import "../../../chunk-AHV4GDYM.js";
 import "../../../chunk-SQDOBLBP.js";
 import "../../../chunk-JEINYUJH.js";
-import "../../../chunk-S7C6TIIF.js";
+import "../../../chunk-S5G3HO7N.js";
 import "../../../chunk-MZ6GV4YF.js";
 import "../../../chunk-U64T4YZE.js";
 import "../../../chunk-2E224ZSN.js";

package/dist/runtime/subsystems/integration/integration.tokens.d.ts

@@ -23,6 +23,16 @@ declare const INTEGRATION_CHANGE_SOURCE: "INTEGRATION_CHANGE_SOURCE";
 declare const INTEGRATION_CURSOR_STORE: "INTEGRATION_CURSOR_STORE";
 declare const INTEGRATION_FIELD_DIFFER: "INTEGRATION_FIELD_DIFFER";
 declare const INTEGRATION_SINK: "INTEGRATION_SINK";
+/**
+ * Optional post-upsert change-event emitter token (EMIT-CHANGES seam).
+ *
+ * Backed by `IIntegrationChangeEmitter`. Bound ONLY by codegen-emitted assembly
+ * modules whose entity opts in via `integration.sink.emit_changes: true`. The
+ * orchestrator injects it `@Optional()` — an unbound token means no domain
+ * events are published (the back-compat default for non-opted-in entities).
+ * See `integration-change-emitter.protocol.ts`.
+ */
+declare const INTEGRATION_CHANGE_EMITTER: "INTEGRATION_CHANGE_EMITTER";
 /**
  * Run-recorder token (SYNC-5). Backed by `IIntegrationRunRecorder`. Drizzle impl
  * lands in SYNC-4; tests provide inline fakes.
@@ -57,4 +67,4 @@ declare const INTEGRATION_MULTI_TENANT: "INTEGRATION_MULTI_TENANT";
  */
 declare const ENTITY_CHANGE_SOURCE_REGISTRY: "ENTITY_CHANGE_SOURCE_REGISTRY";
 
-export { ENTITY_CHANGE_SOURCE_REGISTRY, INTEGRATION_CHANGE_SOURCE, INTEGRATION_CURSOR_STORE, INTEGRATION_FIELD_DIFFER, INTEGRATION_MODULE_OPTIONS, INTEGRATION_MULTI_TENANT, INTEGRATION_RUN_RECORDER, INTEGRATION_SINK };
+export { ENTITY_CHANGE_SOURCE_REGISTRY, INTEGRATION_CHANGE_EMITTER, INTEGRATION_CHANGE_SOURCE, INTEGRATION_CURSOR_STORE, INTEGRATION_FIELD_DIFFER, INTEGRATION_MODULE_OPTIONS, INTEGRATION_MULTI_TENANT, INTEGRATION_RUN_RECORDER, INTEGRATION_SINK };

package/dist/runtime/subsystems/integration/integration.tokens.js

@@ -1,5 +1,6 @@
 import {
   ENTITY_CHANGE_SOURCE_REGISTRY,
+  INTEGRATION_CHANGE_EMITTER,
   INTEGRATION_CHANGE_SOURCE,
   INTEGRATION_CURSOR_STORE,
   INTEGRATION_FIELD_DIFFER,
@@ -7,10 +8,11 @@ import {
   INTEGRATION_MULTI_TENANT,
   INTEGRATION_RUN_RECORDER,
   INTEGRATION_SINK
-} from "../../../chunk-S7C6TIIF.js";
+} from "../../../chunk-S5G3HO7N.js";
 import "../../../chunk-2E224ZSN.js";
 export {
   ENTITY_CHANGE_SOURCE_REGISTRY,
+  INTEGRATION_CHANGE_EMITTER,
   INTEGRATION_CHANGE_SOURCE,
   INTEGRATION_CURSOR_STORE,
   INTEGRATION_FIELD_DIFFER,

package/dist/runtime/subsystems/jobs/index.js

@@ -2,7 +2,7 @@ import "../../../chunk-W4HOHZVF.js";
 import {
   JobWorkerModule,
   JobWorkerOrchestrator
-} from "../../../chunk-QXVCRA23.js";
+} from "../../../chunk-ENAR3F5S.js";
 import {
   JOB_WORKER_OPTIONS,
   JobWorker,
@@ -10,13 +10,10 @@ import {
   buildStaleSweepQuery,
   classifyError,
   computeBackoff
-} from "../../../chunk-VDL5CJ5C.js";
+} from "../../../chunk-7B7MMDOJ.js";
 import {
   JobsDomainModule
-} from "../../../chunk-6DQEIXYU.js";
-import {
-  MemoryJobOrchestrator
-} from "../../../chunk-VQOAATIG.js";
+} from "../../../chunk-CKLM57IE.js";
 import {
   DrizzleJobRunService
 } from "../../../chunk-3VEVGL74.js";
@@ -27,12 +24,6 @@ import "../../../chunk-L3LZWWSX.js";
 import {
   DrizzleJobStepService
 } from "../../../chunk-DV4RV2DC.js";
-import {
-  MemoryJobStepService
-} from "../../../chunk-PNZSGAB2.js";
-import {
-  MemoryJobStore
-} from "../../../chunk-SNQ3TOWP.js";
 import {
   BULLMQ_CONNECTION,
   BULLMQ_RESOLVED_CONFIG,
@@ -49,6 +40,15 @@ import {
 import {
   DrizzleJobOrchestrator
 } from "../../../chunk-E6PLM6QG.js";
+import {
+  MemoryJobOrchestrator
+} from "../../../chunk-VQOAATIG.js";
+import {
+  MemoryJobStepService
+} from "../../../chunk-PNZSGAB2.js";
+import {
+  MemoryJobStore
+} from "../../../chunk-SNQ3TOWP.js";
 import {
   BootValidationError,
   JobCollisionError,