@pattern-stack/codegen 0.23.0 → 0.25.0

package/dist/src/index.d.ts

@@ -1531,12 +1531,15 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.Z
         sink: z.ZodOptional<z.ZodObject<{
             delete: z.ZodOptional<z.ZodEnum<["soft", "tombstone", "noop"]>>;
             exclude_fields: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            emit_changes: z.ZodOptional<z.ZodBoolean>;
         }, "strict", z.ZodTypeAny, {
             delete?: "noop" | "soft" | "tombstone" | undefined;
             exclude_fields?: string[] | undefined;
+            emit_changes?: boolean | undefined;
         }, {
             delete?: "noop" | "soft" | "tombstone" | undefined;
             exclude_fields?: string[] | undefined;
+            emit_changes?: boolean | undefined;
         }>>;
     }, "strip", z.ZodTypeAny, {
         electric: boolean;
@@ -1550,6 +1553,7 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.Z
         sink?: {
             delete?: "noop" | "soft" | "tombstone" | undefined;
             exclude_fields?: string[] | undefined;
+            emit_changes?: boolean | undefined;
         } | undefined;
     }, {
         electric?: boolean | undefined;
@@ -1563,6 +1567,7 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.Z
         sink?: {
             delete?: "noop" | "soft" | "tombstone" | undefined;
             exclude_fields?: string[] | undefined;
+            emit_changes?: boolean | undefined;
         } | undefined;
     }>>;
     detection: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<"mode", [z.ZodObject<{
@@ -2208,6 +2213,7 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.Z
         sink?: {
             delete?: "noop" | "soft" | "tombstone" | undefined;
             exclude_fields?: string[] | undefined;
+            emit_changes?: boolean | undefined;
         } | undefined;
     } | undefined;
     detection?: Record<string, {
@@ -2425,6 +2431,7 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.Z
         sink?: {
             delete?: "noop" | "soft" | "tombstone" | undefined;
             exclude_fields?: string[] | undefined;
+            emit_changes?: boolean | undefined;
         } | undefined;
     } | undefined;
     detection?: Record<string, {
@@ -2642,6 +2649,7 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.Z
         sink?: {
             delete?: "noop" | "soft" | "tombstone" | undefined;
             exclude_fields?: string[] | undefined;
+            emit_changes?: boolean | undefined;
         } | undefined;
     } | undefined;
     detection?: Record<string, {
@@ -2859,6 +2867,7 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.Z
         sink?: {
             delete?: "noop" | "soft" | "tombstone" | undefined;
             exclude_fields?: string[] | undefined;
+            emit_changes?: boolean | undefined;
         } | undefined;
     } | undefined;
     detection?: Record<string, {
@@ -3076,6 +3085,7 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.Z
         sink?: {
             delete?: "noop" | "soft" | "tombstone" | undefined;
             exclude_fields?: string[] | undefined;
+            emit_changes?: boolean | undefined;
         } | undefined;
     } | undefined;
     detection?: Record<string, {
@@ -3293,6 +3303,7 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.Z
         sink?: {
             delete?: "noop" | "soft" | "tombstone" | undefined;
             exclude_fields?: string[] | undefined;
+            emit_changes?: boolean | undefined;
         } | undefined;
     } | undefined;
     detection?: Record<string, {
@@ -3510,6 +3521,7 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.Z
         sink?: {
             delete?: "noop" | "soft" | "tombstone" | undefined;
             exclude_fields?: string[] | undefined;
+            emit_changes?: boolean | undefined;
         } | undefined;
     } | undefined;
     detection?: Record<string, {
@@ -3727,6 +3739,7 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.Z
         sink?: {
             delete?: "noop" | "soft" | "tombstone" | undefined;
             exclude_fields?: string[] | undefined;
+            emit_changes?: boolean | undefined;
         } | undefined;
     } | undefined;
     detection?: Record<string, {

package/dist/src/index.js

@@ -45,13 +45,13 @@ import {
   validateOrchestrationProject,
   validatePatternComposition,
   validatePatternProject
-} from "../chunk-4M66MQYA.js";
+} from "../chunk-K4BQQ2NN.js";
 import "../chunk-KVOWSC5S.js";
-import "../chunk-QFUIE37H.js";
-import "../chunk-FFUDEIFF.js";
-import "../chunk-EO2QPOKH.js";
 import "../chunk-PRWIX6UW.js";
-import "../chunk-O2A6XHGD.js";
+import "../chunk-KFXXOFDC.js";
+import "../chunk-HN5HT5WL.js";
+import "../chunk-EO2QPOKH.js";
+import "../chunk-LLDJS7PJ.js";
 import "../chunk-HNWZFNKP.js";
 import "../chunk-AHV4GDYM.js";
 import "../chunk-SQDOBLBP.js";
@@ -62,8 +62,8 @@ import "../chunk-JEINYUJH.js";
 import "../chunk-5TK7MEN4.js";
 import "../chunk-4KNXX6TI.js";
 import "../chunk-3CJFPU6Q.js";
-import "../chunk-TDEHU73T.js";
-import "../chunk-S7C6TIIF.js";
+import "../chunk-YIVQ7KLS.js";
+import "../chunk-S5G3HO7N.js";
 import "../chunk-MZ6GV4YF.js";
 import "../chunk-LG57S2SC.js";
 import "../chunk-U64T4YZE.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pattern-stack/codegen",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "Entity-driven code generation for full-stack TypeScript applications",
   "license": "MIT",
   "type": "module",

package/runtime/base-classes/lifecycle-events.ts

@@ -23,8 +23,17 @@
  */
 
 import { randomUUID } from 'crypto';
+import { Logger } from '@nestjs/common';
 import type { IEventBus, DomainEvent } from '../subsystems/events/event-bus.protocol';
 
+/**
+ * Module-level logger for fire-and-forget emission failures. Routed through the
+ * Nest `Logger` (not bare `console`) so consumers configuring `app.useLogger`
+ * or the factory `logger:` option can format and filter it like any other
+ * framework log line.
+ */
+const logger = new Logger('LifecycleEvents');
+
 // ============================================================================
 // Event categories (subset of pattern-stack's EventCategory)
 // ============================================================================
@@ -99,7 +108,17 @@ export function buildLifecycleEvent(
 		aggregateType: entityName,
 		payload: snapshot ? { snapshot } : {},
 		occurredAt: new Date(),
-		metadata: { category: 'lifecycle' as EventCategory },
+		// AUDIT tier: lifecycle/change events are untyped audit-trail records —
+		// never bridge-routed, no pool/direction. The `domain_events`
+		// `domain_events_tier_routing_check` CHECK requires `tier='audit' ⇔
+		// (pool IS NULL AND direction IS NULL)`; the DEFAULT `tier='domain'`
+		// (applied by toInsertValues when absent) requires non-null routing
+		// fields, so an un-tiered lifecycle row violates the constraint and the
+		// INSERT is rejected — silently, pre-fix, by emitSafely's catch. Stamp
+		// `tier:'audit'` so these rows land (and surface under the
+		// observability viewer's audit-tier toggle). The bridge guard keeps
+		// audit-tier events out of job routing.
+		metadata: { category: 'lifecycle' as EventCategory, tier: 'audit' },
 	};
 }
 
@@ -119,7 +138,9 @@ export function buildChangeEvents(
 			newValue: c.newValue,
 		},
 		occurredAt: new Date(),
-		metadata: { category: 'change' as EventCategory },
+		// AUDIT tier — see buildLifecycleEvent. Change events are audit-trail
+		// records; tier:'audit' satisfies the tier-routing CHECK constraint.
+		metadata: { category: 'change' as EventCategory, tier: 'audit' },
 	}));
 }
 
@@ -144,9 +165,21 @@ export async function emitSafely(
 		} else {
 			await eventBus.publishMany(events);
 		}
-	} catch {
-		// Log but never fail the CRUD operation.
-		// In production, this would use a structured logger.
-		console.warn(`[lifecycle-events] failed to emit ${events.length} event(s)`);
+	} catch (err) {
+		// Never fail the CRUD operation — but surface the cause. The bare
+		// `catch` that used to live here swallowed the error entirely, so a
+		// failing bus printed `failed to emit N event(s)` with zero
+		// diagnosability. Route through the Nest Logger (not bare console) at
+		// warn level, including the distinct event types and the error message;
+		// the stack follows at debug so it's available without noising the
+		// default-threshold output.
+		const message = err instanceof Error ? err.message : String(err);
+		const types = [...new Set(events.map((e) => e.type))].join(', ');
+		logger.warn(
+			`failed to emit ${events.length} event(s) [${types}]: ${message}`,
+		);
+		if (err instanceof Error && err.stack) {
+			logger.debug(err.stack);
+		}
 	}
 }

package/runtime/subsystems/events/generated/registry.ts

@@ -71,6 +71,33 @@ export const eventRegistry = {
 		version: 1,
 		retry: { attempts: 3, backoff: 'exponential' },
 	},
+	'message_created': {
+		type: 'message_created',
+		tier: 'domain',
+		direction: 'change',
+		pool: 'events_change',
+		aggregate: 'message',
+		version: 1,
+		retry: { attempts: 3, backoff: 'exponential' },
+	},
+	'message_deleted': {
+		type: 'message_deleted',
+		tier: 'domain',
+		direction: 'change',
+		pool: 'events_change',
+		aggregate: 'message',
+		version: 1,
+		retry: { attempts: 3, backoff: 'exponential' },
+	},
+	'message_edited': {
+		type: 'message_edited',
+		tier: 'domain',
+		direction: 'change',
+		pool: 'events_change',
+		aggregate: 'message',
+		version: 1,
+		retry: { attempts: 3, backoff: 'exponential' },
+	},
 	'stripe_payment_received': {
 		type: 'stripe_payment_received',
 		tier: 'domain',

package/runtime/subsystems/events/generated/schemas.ts

@@ -39,6 +39,29 @@ export const dealStageChangedPayloadSchema = z.object({
 	oldStage: z.string(),
 }).strict();
 
+export const messageCreatedPayloadSchema = z.object({
+	changedFields: z.record(z.unknown()).nullable(),
+	entityId: z.string().uuid(),
+	externalId: z.string(),
+	provider: z.string(),
+	source: z.string(),
+}).strict();
+
+export const messageDeletedPayloadSchema = z.object({
+	entityId: z.string().uuid(),
+	externalId: z.string(),
+	provider: z.string(),
+	source: z.string(),
+}).strict();
+
+export const messageEditedPayloadSchema = z.object({
+	changedFields: z.record(z.unknown()).nullable(),
+	entityId: z.string().uuid(),
+	externalId: z.string(),
+	provider: z.string(),
+	source: z.string(),
+}).strict();
+
 export const stripePaymentReceivedPayloadSchema = z.object({
 	amountCents: z.number(),
 	currency: z.string(),
@@ -60,6 +83,9 @@ export const eventPayloadSchemas = {
 	'crm_sync_started': crmSyncStartedPayloadSchema,
 	'deal_created': dealCreatedPayloadSchema,
 	'deal_stage_changed': dealStageChangedPayloadSchema,
+	'message_created': messageCreatedPayloadSchema,
+	'message_deleted': messageDeletedPayloadSchema,
+	'message_edited': messageEditedPayloadSchema,
 	'stripe_payment_received': stripePaymentReceivedPayloadSchema,
 	'webhook_outbound_contact_sync': webhookOutboundContactSyncPayloadSchema,
 } as const satisfies Record<EventTypeName, z.ZodType>;

package/runtime/subsystems/events/generated/types.ts

@@ -64,6 +64,55 @@ export interface DealStageChangedEvent extends DomainEvent {
 	};
 }
 
+export interface MessageCreatedEvent extends DomainEvent {
+	readonly type: 'message_created';
+	readonly aggregateType: 'message';
+	readonly payload: {
+		/** Differ's per-field before/after map (same value as integration_run_items.changed_fields). */
+		changedFields: Record<string, unknown> | null;
+		/** Local aggregate id the sink wrote/soft-deleted. */
+		entityId: string;
+		/** Vendor external id the change keyed on. */
+		externalId: string;
+		/** Provider label (e.g. 'slack', 'google'). */
+		provider: string;
+		/** Provenance marker — always 'integration'. A write-back action reads this to avoid echoing the change back to the vendor. */
+		source: string;
+	};
+}
+
+export interface MessageDeletedEvent extends DomainEvent {
+	readonly type: 'message_deleted';
+	readonly aggregateType: 'message';
+	readonly payload: {
+		/** Local aggregate id the sink wrote/soft-deleted. */
+		entityId: string;
+		/** Vendor external id the change keyed on. */
+		externalId: string;
+		/** Provider label (e.g. 'slack', 'google'). */
+		provider: string;
+		/** Provenance marker — always 'integration'. A write-back action reads this to avoid echoing the change back to the vendor. */
+		source: string;
+	};
+}
+
+export interface MessageEditedEvent extends DomainEvent {
+	readonly type: 'message_edited';
+	readonly aggregateType: 'message';
+	readonly payload: {
+		/** Differ's per-field before/after map (same value as integration_run_items.changed_fields). */
+		changedFields: Record<string, unknown> | null;
+		/** Local aggregate id the sink wrote/soft-deleted. */
+		entityId: string;
+		/** Vendor external id the change keyed on. */
+		externalId: string;
+		/** Provider label (e.g. 'slack', 'google'). */
+		provider: string;
+		/** Provenance marker — always 'integration'. A write-back action reads this to avoid echoing the change back to the vendor. */
+		source: string;
+	};
+}
+
 /** Stripe charge.succeeded webhook, post-signature-verification. */
 export interface StripePaymentReceivedEvent extends DomainEvent {
 	readonly type: 'stripe_payment_received';
@@ -97,6 +146,9 @@ export type AppDomainEvent =
 	| CrmSyncStartedEvent
 	| DealCreatedEvent
 	| DealStageChangedEvent
+	| MessageCreatedEvent
+	| MessageDeletedEvent
+	| MessageEditedEvent
 	| StripePaymentReceivedEvent
 	| WebhookOutboundContactSyncEvent;
 

package/runtime/subsystems/index.ts

@@ -12,6 +12,17 @@ export { EVENT_BUS } from './events';
 // mode reaches it via `@shared/subsystems/events`; both must export it.
 export type { DomainEvent, IEventBus, DrizzleTransaction } from './events';
 export { EventsModule, DrizzleEventBus, MemoryEventBus } from './events';
+// The `TYPED_EVENT_BUS` token is re-exported here so package-mode generated code
+// that publishes events from the single `@pattern-stack/codegen/subsystems`
+// barrel resolves it — notably the EMIT-CHANGES integration change-emitter
+// (`<entity>.change-emitter.ts`), which injects `TYPED_EVENT_BUS`. The emitter
+// types the bus with a local structural `publish` shape (NOT the package's
+// `TypedEventBus`, whose `EventTypeName` union is the package's own events — the
+// consumer's `<entity>_*` events live in the CONSUMER registry), so only the
+// token needs forwarding. The CONSUMER binds their generated `TypedEventBus` to
+// the token via `EventsModule.forRoot()`. Vendored mode reaches it via
+// `@shared/subsystems/events`.
+export { TYPED_EVENT_BUS } from './events';
 
 // Jobs — orchestration schema only (JOB-1). Protocols / modules land in JOB-2 / JOB-5.
 export { jobs, jobRuns, jobSteps } from './jobs';
@@ -131,6 +142,18 @@ export {
 } from './integration';
 export type { IIntegrationSink } from './integration';
 
+// Integration — EMIT-CHANGES seam. The generated per-entity change-emitter
+// (`<entity>.change-emitter.ts`) imports the `INTEGRATION_CHANGE_EMITTER` token
+// + the `IIntegrationChangeEmitter` port + `IntegrationChangeNotification` from
+// `@pattern-stack/codegen/subsystems`. Forwarded here so the emitted opt-in
+// emitter resolves them across the package boundary (package mode).
+export { INTEGRATION_CHANGE_EMITTER } from './integration';
+export type {
+  IIntegrationChangeEmitter,
+  IntegrationChangeAction,
+  IntegrationChangeNotification,
+} from './integration';
+
 // Auth
 export {
   ENCRYPTION_KEY,

package/runtime/subsystems/integration/execute-integration.use-case.ts

@@ -50,8 +50,13 @@ import type { ICursorStore } from './integration-cursor-store.protocol';
 import type { IFieldDiffer, FieldDiff } from './integration-field-diff.protocol';
 import type { IIntegrationSink } from './integration-sink.protocol';
 import type { IIntegrationRunRecorder } from './integration-run-recorder.protocol';
+import type {
+  IIntegrationChangeEmitter,
+  IntegrationChangeAction,
+} from './integration-change-emitter.protocol';
 import { assertTenantId } from './integration-errors';
 import {
+  INTEGRATION_CHANGE_EMITTER,
   INTEGRATION_CHANGE_SOURCE,
   INTEGRATION_CURSOR_STORE,
   INTEGRATION_FIELD_DIFFER,
@@ -118,6 +123,13 @@ export class ExecuteIntegrationUseCase<T extends Record<string, unknown>> {
     @Optional()
     @Inject(INTEGRATION_MULTI_TENANT)
     private readonly multiTenant: boolean = false,
+    // EMIT-CHANGES seam — optional post-upsert domain-event emitter. Bound only
+    // by codegen-emitted assemblies whose entity opts into
+    // `integration.sink.emit_changes: true`. Unbound (the default) ⇒ no events
+    // published, zero behavior change.
+    @Optional()
+    @Inject(INTEGRATION_CHANGE_EMITTER)
+    private readonly emitter: IIntegrationChangeEmitter | null = null,
   ) {}
 
   async execute(input: ExecuteIntegrationInput<T>): Promise<ExecuteIntegrationResult> {
@@ -263,6 +275,12 @@ export class ExecuteIntegrationUseCase<T extends Record<string, unknown>> {
         changedFields: {},
         tenantId: input.tenantId,
       });
+      // EMIT-CHANGES: a real tombstone (a local row existed and was soft-deleted)
+      // is a `<entity>_deleted` event. A delete that hit no local row is a noop —
+      // nothing changed, nothing to emit.
+      if (result) {
+        await this.emitChange(input, change.externalId, result.id, 'deleted');
+      }
       return;
     }
 
@@ -321,15 +339,65 @@ export class ExecuteIntegrationUseCase<T extends Record<string, unknown>> {
       input.provider,
     );
 
+    const action: IntegrationChangeAction =
+      existing === null ? 'created' : 'updated';
+
     await this.recorder.recordItem({
       integrationRunId: runId,
       entityType: input.subscription.domain,
       externalId: change.externalId,
       localId,
-      operation: existing === null ? 'created' : 'updated',
+      operation: action,
       status: 'success',
       changedFields: diff as FieldDiff,
       tenantId: input.tenantId,
     });
+
+    // EMIT-CHANGES: a real create/update (the diff was NOT noop) publishes a
+    // typed `<entity>_created` / `<entity>_edited` event. The noop-reproject path
+    // above intentionally does NOT emit — the canonical state is unchanged.
+    await this.emitChange(
+      input,
+      change.externalId,
+      localId,
+      action,
+      diff as FieldDiff,
+    );
+  }
+
+  /**
+   * Publish one typed data-level change event via the optional emitter
+   * (EMIT-CHANGES seam). No-op when no emitter is bound (the back-compat
+   * default). A failed publish is logged but never aborts the run — the row is
+   * already written; emission is best-effort (the outbox tx, when the generated
+   * adapter rides on one, gives the at-least-once guarantee, not this try/catch).
+   */
+  private async emitChange(
+    input: ExecuteIntegrationInput<T>,
+    externalId: string,
+    entityId: string,
+    action: IntegrationChangeAction,
+    changedFields?: FieldDiff,
+  ): Promise<void> {
+    if (this.emitter === null) return;
+    try {
+      await this.emitter.emitChange({
+        entityId,
+        externalId,
+        provider: input.provider,
+        action,
+        changedFields:
+          action === 'deleted'
+            ? undefined
+            : (changedFields as Record<string, unknown> | undefined),
+        tenantId: input.tenantId,
+      });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      this.logger.warn(
+        `integration change-emit failed: subscription=${input.subscription.id} ` +
+          `externalId=${externalId} action=${action}: ${message}`,
+      );
+    }
   }
 }

package/runtime/subsystems/integration/index.ts

@@ -35,6 +35,11 @@ export {
   FieldDiffValueSchema,
 } from './integration-field-diff.protocol';
 export type { IIntegrationSink } from './integration-sink.protocol';
+export type {
+  IIntegrationChangeEmitter,
+  IntegrationChangeAction,
+  IntegrationChangeNotification,
+} from './integration-change-emitter.protocol';
 export type {
   CompleteRunInput,
   IIntegrationRunRecorder,
@@ -125,6 +130,7 @@ export { buildChangeSource } from './build-change-source';
 // Tokens
 export {
   ENTITY_CHANGE_SOURCE_REGISTRY,
+  INTEGRATION_CHANGE_EMITTER,
   INTEGRATION_CHANGE_SOURCE,
   INTEGRATION_CURSOR_STORE,
   INTEGRATION_FIELD_DIFFER,

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

@@ -0,0 +1,107 @@
+/**
+ * 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. */
+export 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' }`).
+ */
+export 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).
+ */
+export 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>;
+}

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

@@ -25,6 +25,17 @@ export const INTEGRATION_CURSOR_STORE = 'INTEGRATION_CURSOR_STORE' as const;
 export const INTEGRATION_FIELD_DIFFER = 'INTEGRATION_FIELD_DIFFER' as const;
 export const INTEGRATION_SINK = 'INTEGRATION_SINK' as const;
 
+/**
+ * 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`.
+ */
+export const INTEGRATION_CHANGE_EMITTER = 'INTEGRATION_CHANGE_EMITTER' as const;
+
 /**
  * Run-recorder token (SYNC-5). Backed by `IIntegrationRunRecorder`. Drizzle impl
  * lands in SYNC-4; tests provide inline fakes.

package/templates/subsystem/jobs/job-orchestration.schema.ejs.t

@@ -1,6 +1,7 @@
 ---
 to: "<%= schemaPath %>"
 force: true
+skip_if: "<%= skipSchema %>"
 ---
 <%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 /**

package/templates/subsystem/jobs/main-hook.ejs.t

@@ -7,5 +7,5 @@ skip_if: "<%= mainHookInjected %>"
   // JOBS — Embedded worker mode (optional)
   // To run the job worker in-process (single-process deploy), add to AppModule imports:
   //   JobWorkerModule.forRoot({ mode: 'embedded' })
-  // For standalone worker (separate process), use worker.ts at the project root.
+  // For standalone worker (separate process), run src/worker.ts (bun src/worker.ts).
   // See codegen.config.yaml jobs.worker_mode to toggle the documented default.