@pattern-stack/codegen 0.16.0 → 0.16.1

package/runtime/subsystems/integration/detection-config.schema.ts

@@ -22,10 +22,12 @@
  *     primitive while emitting `Change<T>.source = 'cdc'`. Long-lived
  *     streaming CDC (SFDC Pub-Sub, Debezium) is a separate primitive
  *     deferred to #226-8.
- *   - `webhook` mode requires `eventIdField` so `WebhookChangeSource<T>`
- *     can populate `Change<T>.dedupKey` from the inbound staging row.
+ *   - `webhook` mode's `eventIdField` is optional: `WebhookChangeSource<T>`
+ *     prefers an `eventId` yielded by the queue iterator and falls back to the
+ *     `eventIdField` record extraction (precedence: yielded eventId >
+ *     eventIdField extraction > undefined dedupKey).
  */
-import { z } from 'zod';
+import { z } from "zod";
 
 // ============================================================================
 // Field mapping — provider field → canonical target
@@ -37,9 +39,9 @@ import { z } from 'zod';
  * etc.); the schema does not enumerate transforms — adapters interpret them.
  */
 export const FieldMappingSchema = z.object({
-  source: z.string().min(1),
-  target: z.string().min(1),
-  transform: z.string().min(1).optional(),
+	source: z.string().min(1),
+	target: z.string().min(1),
+	transform: z.string().min(1).optional(),
 });
 
 export type FieldMapping = z.infer<typeof FieldMappingSchema>;
@@ -54,9 +56,9 @@ export type FieldMapping = z.infer<typeof FieldMappingSchema>;
  * adapters interpret per provider.
  */
 export const ResolvedFilterSchema = z.object({
-  field: z.string().min(1),
-  op: z.enum(['eq', 'neq', 'in', 'nin', 'gt', 'gte', 'lt', 'lte']),
-  value: z.unknown(),
+	field: z.string().min(1),
+	op: z.enum(["eq", "neq", "in", "nin", "gt", "gte", "lt", "lte"]),
+	value: z.unknown(),
 });
 
 export type ResolvedFilter = z.infer<typeof ResolvedFilterSchema>;
@@ -66,23 +68,23 @@ export type ResolvedFilter = z.infer<typeof ResolvedFilterSchema>;
 // ============================================================================
 
 const SystemModstampCursorSchema = z.object({
-  kind: z.literal('systemModstamp'),
-  field: z.string().min(1),
+	kind: z.literal("systemModstamp"),
+	field: z.string().min(1),
 });
 
 const ReplayIdCursorSchema = z.object({
-  kind: z.literal('replayId'),
-  field: z.string().min(1),
+	kind: z.literal("replayId"),
+	field: z.string().min(1),
 });
 
 const TimestampCursorSchema = z.object({
-  kind: z.literal('timestamp'),
-  field: z.string().min(1),
+	kind: z.literal("timestamp"),
+	field: z.string().min(1),
 });
 
 const EventIdCursorSchema = z.object({
-  kind: z.literal('eventId'),
-  field: z.string().min(1),
+	kind: z.literal("eventId"),
+	field: z.string().min(1),
 });
 
 /**
@@ -91,8 +93,8 @@ const EventIdCursorSchema = z.object({
  * `field` is metadata for codegen/adapters (the response key the token lives on).
  */
 const HistoryIdCursorSchema = z.object({
-  kind: z.literal('historyId'),
-  field: z.string().min(1),
+	kind: z.literal("historyId"),
+	field: z.string().min(1),
 });
 
 /**
@@ -100,17 +102,17 @@ const HistoryIdCursorSchema = z.object({
  * same divisibility profile as `historyId`.
  */
 const SyncTokenCursorSchema = z.object({
-  kind: z.literal('syncToken'),
-  field: z.string().min(1),
+	kind: z.literal("syncToken"),
+	field: z.string().min(1),
 });
 
-export const CursorStrategySchema = z.discriminatedUnion('kind', [
-  SystemModstampCursorSchema,
-  ReplayIdCursorSchema,
-  TimestampCursorSchema,
-  EventIdCursorSchema,
-  HistoryIdCursorSchema,
-  SyncTokenCursorSchema,
+export const CursorStrategySchema = z.discriminatedUnion("kind", [
+	SystemModstampCursorSchema,
+	ReplayIdCursorSchema,
+	TimestampCursorSchema,
+	EventIdCursorSchema,
+	HistoryIdCursorSchema,
+	SyncTokenCursorSchema,
 ]);
 
 export type CursorStrategy = z.infer<typeof CursorStrategySchema>;
@@ -135,18 +137,20 @@ export type CursorStrategy = z.infer<typeof CursorStrategySchema>;
  * `eventId` is classified atomic conservatively: a generic opaque id is treated
  * all-or-nothing unless a concrete strategy proves it monotonically resumable.
  */
-export const CURSOR_DIVISIBILITY: Readonly<Record<CursorStrategy['kind'], boolean>> = {
-  systemModstamp: true,
-  timestamp: true,
-  replayId: true,
-  eventId: false,
-  historyId: false,
-  syncToken: false,
+export const CURSOR_DIVISIBILITY: Readonly<
+	Record<CursorStrategy["kind"], boolean>
+> = {
+	systemModstamp: true,
+	timestamp: true,
+	replayId: true,
+	eventId: false,
+	historyId: false,
+	syncToken: false,
 };
 
 /** Predicate form of {@link CURSOR_DIVISIBILITY}. */
-export function isDivisibleCursor(kind: CursorStrategy['kind']): boolean {
-  return CURSOR_DIVISIBILITY[kind];
+export function isDivisibleCursor(kind: CursorStrategy["kind"]): boolean {
+	return CURSOR_DIVISIBILITY[kind];
 }
 
 // ============================================================================
@@ -159,19 +163,25 @@ export function isDivisibleCursor(kind: CursorStrategy['kind']): boolean {
  * `field` — used for Stripe-style event endpoints. Defaults to `'poll'`.
  */
 export const PollDetectionSchema = z.object({
-  cursor: CursorStrategySchema,
-  provenance: z.enum(['poll', 'cdc']).optional(),
+	cursor: CursorStrategySchema,
+	provenance: z.enum(["poll", "cdc"]).optional(),
 });
 
 export type PollDetection = z.infer<typeof PollDetectionSchema>;
 
 /**
- * Webhook-mode block. `eventIdField` names the column in the consumer-owned
- * inbound staging row that `WebhookChangeSource<T>` reads to set
- * `Change<T>.dedupKey`.
+ * Webhook-mode block. `eventIdField`, when present, names the field on the
+ * emitted canonical record that `WebhookChangeSource<T>` reads to set
+ * `Change<T>.dedupKey` — used only as the fallback when the queue iterator
+ * does NOT yield an `eventId` alongside the record.
+ *
+ * `eventIdField` is **optional**: a queue iterator that always yields an
+ * `eventId` (vendor delivery metadata, the preferred channel) need not declare
+ * a record field for it. dedupKey precedence is: yielded `eventId` >
+ * `eventIdField` record extraction > undefined.
  */
 export const WebhookDetectionSchema = z.object({
-  eventIdField: z.string().min(1),
+	eventIdField: z.string().min(1).optional(),
 });
 
 export type WebhookDetection = z.infer<typeof WebhookDetectionSchema>;
@@ -181,17 +191,17 @@ export type WebhookDetection = z.infer<typeof WebhookDetectionSchema>;
 // ============================================================================
 
 const PollModeSchema = z.object({
-  mode: z.literal('poll'),
-  poll: PollDetectionSchema,
-  mapping: z.array(FieldMappingSchema).min(1),
-  filters: z.array(ResolvedFilterSchema).default([]),
+	mode: z.literal("poll"),
+	poll: PollDetectionSchema,
+	mapping: z.array(FieldMappingSchema).min(1),
+	filters: z.array(ResolvedFilterSchema).default([]),
 });
 
 const WebhookModeSchema = z.object({
-  mode: z.literal('webhook'),
-  webhook: WebhookDetectionSchema,
-  mapping: z.array(FieldMappingSchema).min(1),
-  filters: z.array(ResolvedFilterSchema).default([]),
+	mode: z.literal("webhook"),
+	webhook: WebhookDetectionSchema,
+	mapping: z.array(FieldMappingSchema).min(1),
+	filters: z.array(ResolvedFilterSchema).default([]),
 });
 
 /**
@@ -201,9 +211,9 @@ const WebhookModeSchema = z.object({
  * (Stripe-style event endpoints) is expressed via `mode: 'poll'` with
  * `poll.provenance: 'cdc'`.
  */
-export const DetectionConfigSchema = z.discriminatedUnion('mode', [
-  PollModeSchema,
-  WebhookModeSchema,
+export const DetectionConfigSchema = z.discriminatedUnion("mode", [
+	PollModeSchema,
+	WebhookModeSchema,
 ]);
 
 export type DetectionConfig = z.infer<typeof DetectionConfigSchema>;

package/runtime/subsystems/integration/webhook-change-source.ts

@@ -7,8 +7,11 @@
  * queue. The primitive owns:
  *
  *   - canonical `Change<T>.source = 'webhook'` stamping;
- *   - `dedupKey` derivation from the configured `webhook.eventIdField` on
- *     the emitted record;
+ *   - `dedupKey` derivation, preferring the `eventId` yielded alongside the
+ *     record by the queue iterator, and falling back to the configured
+ *     `webhook.eventIdField` on the emitted record when no `eventId` is yielded
+ *     (precedence: yielded `eventId` > `eventIdField` record extraction >
+ *     undefined `dedupKey`);
  *   - `externalId` derivation: the mapping entry whose `target === 'external_id'`
  *     names — via its `source` — the field on the emitted record that carries
  *     the canonical external id (mirrors `PollChangeSource`);
@@ -37,16 +40,16 @@
  * into either this primitive or the poll primitive.
  */
 
-import type { DetectionConfig } from './detection-config.schema';
+import type { DetectionConfig } from "./detection-config.schema";
 import type {
-  Change,
-  IChangeSource,
-  IntegrationSubscriptionView,
-} from './integration-change-source.protocol';
+	Change,
+	IChangeSource,
+	IntegrationSubscriptionView,
+} from "./integration-change-source.protocol";
 import type {
-  ChangeIterator,
-  ChangeMiddleware,
-} from './integration-middleware.protocol';
+	ChangeIterator,
+	ChangeMiddleware,
+} from "./integration-middleware.protocol";
 
 // ============================================================================
 // Cursor + queue callback shapes
@@ -66,16 +69,28 @@ export type WebhookCursor = unknown;
  * `userId` / `tenantId`.
  */
 export interface WebhookFetchContext {
-  readonly subscription: IntegrationSubscriptionView;
-  readonly cursor: WebhookCursor | null;
+	readonly subscription: IntegrationSubscriptionView;
+	readonly cursor: WebhookCursor | null;
 }
 
 /**
  * Consumer-supplied queue iterator. Returns an async iterable of
- * `{ record }` pairs — the consumer drains the inbound staging queue and
- * emits already-mapped canonical records `T`. The primitive stamps
- * `source: 'webhook'` and `dedupKey` from the record's configured
- * `webhook.eventIdField`; the consumer is the one who decided when a
+ * `{ record, eventId?, cursor? }` tuples — the consumer drains the inbound
+ * staging queue and emits already-mapped canonical records `T`. The primitive
+ * stamps `source: 'webhook'` and derives `dedupKey` with this precedence:
+ *
+ *   1. the yielded `eventId` (vendor delivery metadata — the queue is the
+ *      right channel for it: a vendor's event id should never need a field
+ *      on the vendor-neutral canonical record);
+ *   2. else the record field named by `webhook.eventIdField`, when configured;
+ *   3. else `undefined`.
+ *
+ * Yielding `eventId` is the safe channel when one canonical record identity
+ * (the `external_id`) can recur across distinct vendor events in a single
+ * drain batch — e.g. a message create and its later edit share an
+ * `external_id` but are different events. Reading dedup identity off the
+ * record (`eventIdField`) collapses those into one `dedupKey`; the yielded
+ * `eventId` keeps them distinct. The consumer is the one who decided when a
  * staging row is "ready" to drain.
  *
  * Webhook mode has no per-record cursor advance — the staging-row drain
@@ -84,33 +99,33 @@ export interface WebhookFetchContext {
  * is whatever the consumer chooses to surface, if anything.
  */
 export type WebhookFetchCallback<T> = (
-  ctx: WebhookFetchContext,
-) => AsyncIterable<{ record: T; cursor?: WebhookCursor }>;
+	ctx: WebhookFetchContext,
+) => AsyncIterable<{ record: T; eventId?: string; cursor?: WebhookCursor }>;
 
 // ============================================================================
 // Constructor options
 // ============================================================================
 
 export interface WebhookChangeSourceOptions<T> {
-  /** Consumer-supplied inbound queue iterator. */
-  readonly queue: WebhookFetchCallback<T>;
-  /**
-   * Parsed detection config. MUST be `mode: 'webhook'`; the constructor
-   * throws if a poll config is supplied. Codegen-emitted factories call
-   * `DetectionConfigSchema.parse(...)` upstream so this is a safety net,
-   * not the primary validation point.
-   */
-  readonly config: DetectionConfig;
-  /**
-   * Optional middleware chain. Same shape and composition rules as
-   * `PollChangeSource` — first element is the outermost layer.
-   */
-  readonly middlewares?: ReadonlyArray<ChangeMiddleware<T>>;
-  /**
-   * Optional human label for run logs (e.g. `'stripe-webhook-charge'`).
-   * Defaults to a derived label based on the mapping at construction.
-   */
-  readonly label?: string;
+	/** Consumer-supplied inbound queue iterator. */
+	readonly queue: WebhookFetchCallback<T>;
+	/**
+	 * Parsed detection config. MUST be `mode: 'webhook'`; the constructor
+	 * throws if a poll config is supplied. Codegen-emitted factories call
+	 * `DetectionConfigSchema.parse(...)` upstream so this is a safety net,
+	 * not the primary validation point.
+	 */
+	readonly config: DetectionConfig;
+	/**
+	 * Optional middleware chain. Same shape and composition rules as
+	 * `PollChangeSource` — first element is the outermost layer.
+	 */
+	readonly middlewares?: ReadonlyArray<ChangeMiddleware<T>>;
+	/**
+	 * Optional human label for run logs (e.g. `'stripe-webhook-charge'`).
+	 * Defaults to a derived label based on the mapping at construction.
+	 */
+	readonly label?: string;
 }
 
 // ============================================================================
@@ -118,100 +133,139 @@ export interface WebhookChangeSourceOptions<T> {
 // ============================================================================
 
 export class WebhookChangeSource<T> implements IChangeSource<T> {
-  public readonly label: string;
-
-  private readonly queue: WebhookFetchCallback<T>;
-  private readonly externalIdSourceField: string;
-  private readonly eventIdSourceField: string;
-  private readonly composed: ChangeIterator<T>;
-
-  constructor(opts: WebhookChangeSourceOptions<T>) {
-    if (opts.config.mode !== 'webhook') {
-      throw new Error(
-        `WebhookChangeSource requires DetectionConfig.mode === 'webhook'; got '${(opts.config as { mode: string }).mode}'`,
-      );
-    }
-    const config = opts.config;
-
-    // Field mapping: locate the entry whose canonical `target` is `external_id`
-    // — mirrors the poll primitive's contract. Adapters emit records
-    // already-mapped; the primitive needs to know which key on T carries the
-    // external id so it can stamp `Change.externalId`. That key is the
-    // mapping's `source` (the field on the emitted record), NOT its `target`
-    // (the canonical column) — they differ whenever the canonical record is
-    // vendor-neutral camelCase (e.g. `source: 'externalId'` → `target: 'external_id'`).
-    const externalIdMapping = config.mapping.find(
-      (m) => m.target === 'external_id',
-    );
-    if (!externalIdMapping) {
-      throw new Error(
-        "WebhookChangeSource: DetectionConfig.mapping must include an entry with target 'external_id' so emitted Change<T>.externalId can be populated",
-      );
-    }
-    this.externalIdSourceField = externalIdMapping.source;
-    this.eventIdSourceField = config.webhook.eventIdField;
-
-    this.queue = opts.queue;
-
-    this.label =
-      opts.label ?? `webhook-change-source:${externalIdMapping.source}`;
-
-    // Compose middleware chain — same shape as PollChangeSource.
-    const inner: ChangeIterator<T> = (sub, cur) => this.fetch(sub, cur);
-    const middlewares = opts.middlewares ?? [];
-    this.composed = middlewares.reduceRight<ChangeIterator<T>>(
-      (next, mw) => mw(next),
-      inner,
-    );
-  }
-
-  listChanges(
-    subscription: IntegrationSubscriptionView,
-    cursor: unknown | null,
-  ): AsyncIterable<Change<T>> {
-    return this.composed(subscription, cursor);
-  }
-
-  private async *fetch(
-    subscription: IntegrationSubscriptionView,
-    cursor: unknown | null,
-  ): AsyncIterable<Change<T>> {
-    const ctx: WebhookFetchContext = {
-      subscription,
-      cursor: cursor as WebhookCursor | null,
-    };
-
-    for await (const { record, cursor: nextCursor } of this.queue(ctx)) {
-      const externalIdRaw = (record as Record<string, unknown>)[
-        this.externalIdSourceField
-      ];
-      if (typeof externalIdRaw !== 'string' || externalIdRaw.length === 0) {
-        throw new Error(
-          `WebhookChangeSource: record missing string '${this.externalIdSourceField}' — emitted records MUST carry the canonical external id keyed by the mapping source`,
-        );
-      }
-      const eventIdRaw = (record as Record<string, unknown>)[
-        this.eventIdSourceField
-      ];
-      if (typeof eventIdRaw !== 'string' || eventIdRaw.length === 0) {
-        throw new Error(
-          `WebhookChangeSource: record missing string '${this.eventIdSourceField}' — webhook records MUST carry the event id (DetectionConfig.webhook.eventIdField) so Change<T>.dedupKey can be populated`,
-        );
-      }
-
-      const change: Change<T> = {
-        externalId: externalIdRaw,
-        // Webhook mode cannot distinguish create vs. update vs. delete on
-        // its own — the orchestrator's diff stage handles classification.
-        // Tombstone / soft-delete detection is consumer-driven (same as
-        // poll mode — see ADR-033).
-        operation: 'updated',
-        record,
-        cursor: nextCursor ?? null,
-        source: 'webhook',
-        dedupKey: eventIdRaw,
-      };
-      yield change;
-    }
-  }
+	public readonly label: string;
+
+	private readonly queue: WebhookFetchCallback<T>;
+	private readonly externalIdSourceField: string;
+	/**
+	 * Record field carrying the event id, when `webhook.eventIdField` is
+	 * configured. Used only as the fallback when the queue iterator does NOT
+	 * yield an `eventId` — see {@link WebhookFetchCallback} for the precedence.
+	 */
+	private readonly eventIdSourceField: string | undefined;
+	private readonly composed: ChangeIterator<T>;
+
+	constructor(opts: WebhookChangeSourceOptions<T>) {
+		if (opts.config.mode !== "webhook") {
+			throw new Error(
+				`WebhookChangeSource requires DetectionConfig.mode === 'webhook'; got '${(opts.config as { mode: string }).mode}'`,
+			);
+		}
+		const config = opts.config;
+
+		// Field mapping: locate the entry whose canonical `target` is `external_id`
+		// — mirrors the poll primitive's contract. Adapters emit records
+		// already-mapped; the primitive needs to know which key on T carries the
+		// external id so it can stamp `Change.externalId`. That key is the
+		// mapping's `source` (the field on the emitted record), NOT its `target`
+		// (the canonical column) — they differ whenever the canonical record is
+		// vendor-neutral camelCase (e.g. `source: 'externalId'` → `target: 'external_id'`).
+		const externalIdMapping = config.mapping.find(
+			(m) => m.target === "external_id",
+		);
+		if (!externalIdMapping) {
+			throw new Error(
+				"WebhookChangeSource: DetectionConfig.mapping must include an entry with target 'external_id' so emitted Change<T>.externalId can be populated",
+			);
+		}
+		this.externalIdSourceField = externalIdMapping.source;
+		this.eventIdSourceField = config.webhook.eventIdField;
+		// `eventIdField` is optional (a callback that always yields `eventId` need
+		// not declare one); `undefined` here just disables the fallback extraction.
+
+		this.queue = opts.queue;
+
+		this.label =
+			opts.label ?? `webhook-change-source:${externalIdMapping.source}`;
+
+		// Compose middleware chain — same shape as PollChangeSource.
+		const inner: ChangeIterator<T> = (sub, cur) => this.fetch(sub, cur);
+		const middlewares = opts.middlewares ?? [];
+		this.composed = middlewares.reduceRight<ChangeIterator<T>>(
+			(next, mw) => mw(next),
+			inner,
+		);
+	}
+
+	listChanges(
+		subscription: IntegrationSubscriptionView,
+		cursor: unknown | null,
+	): AsyncIterable<Change<T>> {
+		return this.composed(subscription, cursor);
+	}
+
+	private async *fetch(
+		subscription: IntegrationSubscriptionView,
+		cursor: unknown | null,
+	): AsyncIterable<Change<T>> {
+		const ctx: WebhookFetchContext = {
+			subscription,
+			cursor: cursor as WebhookCursor | null,
+		};
+
+		for await (const {
+			record,
+			eventId: yieldedEventId,
+			cursor: nextCursor,
+		} of this.queue(ctx)) {
+			const externalIdRaw = (record as Record<string, unknown>)[
+				this.externalIdSourceField
+			];
+			if (typeof externalIdRaw !== "string" || externalIdRaw.length === 0) {
+				throw new Error(
+					`WebhookChangeSource: record missing string '${this.externalIdSourceField}' — emitted records MUST carry the canonical external id keyed by the mapping source`,
+				);
+			}
+
+			// dedupKey precedence: yielded `eventId` > `eventIdField` record
+			// extraction > undefined. The yielded id is vendor delivery metadata
+			// (the right channel for it), and keeps distinct vendor events for the
+			// same `external_id` (e.g. a message and its edit) from collapsing to
+			// one dedupKey — which a record-field extraction would do.
+			const dedupKey = this.deriveDedupKey(yieldedEventId, record);
+
+			const change: Change<T> = {
+				externalId: externalIdRaw,
+				// Webhook mode cannot distinguish create vs. update vs. delete on
+				// its own — the orchestrator's diff stage handles classification.
+				// Tombstone / soft-delete detection is consumer-driven (same as
+				// poll mode — see ADR-033).
+				operation: "updated",
+				record,
+				cursor: nextCursor ?? null,
+				source: "webhook",
+				dedupKey,
+			};
+			yield change;
+		}
+	}
+
+	/**
+	 * Resolve `Change<T>.dedupKey` with the precedence: yielded `eventId` >
+	 * `webhook.eventIdField` record extraction > `undefined`. A non-empty
+	 * yielded `eventId` always wins; otherwise the configured field is read off
+	 * the record (and must be a non-empty string when the field is configured);
+	 * with neither, `dedupKey` is `undefined` (the orchestrator then has no
+	 * delivery-level dedup signal for this change).
+	 */
+	private deriveDedupKey(
+		yieldedEventId: string | undefined,
+		record: T,
+	): string | undefined {
+		if (yieldedEventId !== undefined && yieldedEventId.length > 0) {
+			return yieldedEventId;
+		}
+		if (this.eventIdSourceField === undefined) {
+			return undefined;
+		}
+		const eventIdRaw = (record as Record<string, unknown>)[
+			this.eventIdSourceField
+		];
+		if (typeof eventIdRaw !== "string" || eventIdRaw.length === 0) {
+			throw new Error(
+				`WebhookChangeSource: record missing string '${this.eventIdSourceField}' — a webhook record MUST carry the event id (DetectionConfig.webhook.eventIdField) so Change<T>.dedupKey can be populated, unless the queue iterator yields an 'eventId' alongside the record`,
+			);
+		}
+		return eventIdRaw;
+	}
 }

package/dist/chunk-3NMCDN7L.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../runtime/subsystems/integration/detection-config.schema.ts"],"sourcesContent":["/**\n * Integration subsystem — DetectionConfig schema (#226-1)\n *\n * Canonical Zod schema for per-entity integration detection config. The schema is\n * the single source of truth for filter/mapping shape and is consumed by:\n *\n *   1. Runtime primitives — `PollChangeSource<T>`, `WebhookChangeSource<T>`\n *      (#226-3, #226-4) accept a parsed `DetectionConfig` at construction.\n *   2. Codegen — `src/schema/entity-definition.schema.ts` (#226-6) imports\n *      this schema so per-entity YAML `detection:` blocks validate against\n *      the same shape the runtime enforces.\n *\n * Locked decisions (see ADR-033 + decision memo Q1–Q6):\n *   - Filter vocabulary is flat AND of `{ field, op, value }` triples; richer\n *     boolean expressions (OR / NOT / nested) are deferred per epic open Q3.\n *   - Cursor strategy is a tagged union over the four shapes the three modes\n *     need (`systemModstamp`, `replayId`, `timestamp`, `eventId`). Each\n *     strategy types its cursor internally; the orchestrator persists what\n *     the iterator last yielded (integration skill rule 2).\n *   - `mode: 'poll'` may opt into `provenance: 'cdc'` so Stripe-style event\n *     endpoints (mechanically a poll, semantically CDC) reuse the poll\n *     primitive while emitting `Change<T>.source = 'cdc'`. Long-lived\n *     streaming CDC (SFDC Pub-Sub, Debezium) is a separate primitive\n *     deferred to #226-8.\n *   - `webhook` mode requires `eventIdField` so `WebhookChangeSource<T>`\n *     can populate `Change<T>.dedupKey` from the inbound staging row.\n */\nimport { z } from 'zod';\n\n// ============================================================================\n// Field mapping — provider field → canonical target\n// ============================================================================\n\n/**\n * Maps a single provider field onto the canonical record. `transform` is an\n * opt-in tag the adapter callback may inspect (`date-iso`, `decimal-string`,\n * etc.); the schema does not enumerate transforms — adapters interpret them.\n */\nexport const FieldMappingSchema = z.object({\n  source: z.string().min(1),\n  target: z.string().min(1),\n  transform: z.string().min(1).optional(),\n});\n\nexport type FieldMapping = z.infer<typeof FieldMappingSchema>;\n\n// ============================================================================\n// Resolved filter — flat-AND triple\n// ============================================================================\n\n/**\n * A single resolved filter clause applied at fetch time. `value` is `unknown`\n * to admit primitives, arrays (for `in` / `nin`), and dates as ISO strings —\n * adapters interpret per provider.\n */\nexport const ResolvedFilterSchema = z.object({\n  field: z.string().min(1),\n  op: z.enum(['eq', 'neq', 'in', 'nin', 'gt', 'gte', 'lt', 'lte']),\n  value: z.unknown(),\n});\n\nexport type ResolvedFilter = z.infer<typeof ResolvedFilterSchema>;\n\n// ============================================================================\n// Cursor strategy — tagged union over the four shapes the modes need\n// ============================================================================\n\nconst SystemModstampCursorSchema = z.object({\n  kind: z.literal('systemModstamp'),\n  field: z.string().min(1),\n});\n\nconst ReplayIdCursorSchema = z.object({\n  kind: z.literal('replayId'),\n  field: z.string().min(1),\n});\n\nconst TimestampCursorSchema = z.object({\n  kind: z.literal('timestamp'),\n  field: z.string().min(1),\n});\n\nconst EventIdCursorSchema = z.object({\n  kind: z.literal('eventId'),\n  field: z.string().min(1),\n});\n\n/**\n * Gmail `historyId` (RFC-0003 §3) — an opaque, atomic vendor token. The next\n * watermark only exists at end-of-walk; there is no resumable mid-walk value.\n * `field` is metadata for codegen/adapters (the response key the token lives on).\n */\nconst HistoryIdCursorSchema = z.object({\n  kind: z.literal('historyId'),\n  field: z.string().min(1),\n});\n\n/**\n * Google Calendar `syncToken` (RFC-0003 §3) — an opaque, atomic sync token,\n * same divisibility profile as `historyId`.\n */\nconst SyncTokenCursorSchema = z.object({\n  kind: z.literal('syncToken'),\n  field: z.string().min(1),\n});\n\nexport const CursorStrategySchema = z.discriminatedUnion('kind', [\n  SystemModstampCursorSchema,\n  ReplayIdCursorSchema,\n  TimestampCursorSchema,\n  EventIdCursorSchema,\n  HistoryIdCursorSchema,\n  SyncTokenCursorSchema,\n]);\n\nexport type CursorStrategy = z.infer<typeof CursorStrategySchema>;\n\n// ============================================================================\n// Cursor divisibility (RFC-0003 §3)\n// ============================================================================\n\n/**\n * Whether a cursor strategy is *divisible* — a property of the strategy, not\n * the read primitive. Divisible cursors are sortable/monotonic watermarks whose\n * value is meaningful AS OF any single record (HubSpot `systemModstamp`, a\n * `timestamp` field, a Salesforce CDC `replayId`); the read primitive may\n * checkpoint per-ref mid-walk, so a crash resumes from the last delivered ref.\n *\n * Atomic cursors are opaque vendor tokens (Gmail `historyId`, Calendar\n * `syncToken`, a generic `eventId`) whose next value only exists at end-of-walk.\n * The primitive must withhold per-ref cursors and emit the token only at a safe\n * boundary, so an interrupted run never persists an unresumable mid-walk token\n * (it resumes all-or-nothing from the prior token — see `IncrementalReadBase`).\n *\n * `eventId` is classified atomic conservatively: a generic opaque id is treated\n * all-or-nothing unless a concrete strategy proves it monotonically resumable.\n */\nexport const CURSOR_DIVISIBILITY: Readonly<Record<CursorStrategy['kind'], boolean>> = {\n  systemModstamp: true,\n  timestamp: true,\n  replayId: true,\n  eventId: false,\n  historyId: false,\n  syncToken: false,\n};\n\n/** Predicate form of {@link CURSOR_DIVISIBILITY}. */\nexport function isDivisibleCursor(kind: CursorStrategy['kind']): boolean {\n  return CURSOR_DIVISIBILITY[kind];\n}\n\n// ============================================================================\n// Mode-specific blocks\n// ============================================================================\n\n/**\n * Poll-mode block. `provenance: 'cdc'` opts the poll primitive into stamping\n * `Change<T>.source = 'cdc'` and populating `dedupKey` from the cursor's\n * `field` — used for Stripe-style event endpoints. Defaults to `'poll'`.\n */\nexport const PollDetectionSchema = z.object({\n  cursor: CursorStrategySchema,\n  provenance: z.enum(['poll', 'cdc']).optional(),\n});\n\nexport type PollDetection = z.infer<typeof PollDetectionSchema>;\n\n/**\n * Webhook-mode block. `eventIdField` names the column in the consumer-owned\n * inbound staging row that `WebhookChangeSource<T>` reads to set\n * `Change<T>.dedupKey`.\n */\nexport const WebhookDetectionSchema = z.object({\n  eventIdField: z.string().min(1),\n});\n\nexport type WebhookDetection = z.infer<typeof WebhookDetectionSchema>;\n\n// ============================================================================\n// DetectionConfig — top-level discriminated union over `mode`\n// ============================================================================\n\nconst PollModeSchema = z.object({\n  mode: z.literal('poll'),\n  poll: PollDetectionSchema,\n  mapping: z.array(FieldMappingSchema).min(1),\n  filters: z.array(ResolvedFilterSchema).default([]),\n});\n\nconst WebhookModeSchema = z.object({\n  mode: z.literal('webhook'),\n  webhook: WebhookDetectionSchema,\n  mapping: z.array(FieldMappingSchema).min(1),\n  filters: z.array(ResolvedFilterSchema).default([]),\n});\n\n/**\n * Top-level detection config. Discriminated on `mode` so the relevant\n * mode-block (poll/webhook) is structurally required for that mode. CDC as a\n * long-lived streaming primitive is deferred (#226-8); CDC-as-provenance\n * (Stripe-style event endpoints) is expressed via `mode: 'poll'` with\n * `poll.provenance: 'cdc'`.\n */\nexport const DetectionConfigSchema = z.discriminatedUnion('mode', [\n  PollModeSchema,\n  WebhookModeSchema,\n]);\n\nexport type DetectionConfig = z.infer<typeof DetectionConfigSchema>;\n"],"mappings":";AA2BA,SAAS,SAAS;AAWX,IAAM,qBAAqB,EAAE,OAAO;AAAA,EACzC,QAAQ,EAAE,OAAO,EAAE,IAAI,CAAC;AAAA,EACxB,QAAQ,EAAE,OAAO,EAAE,IAAI,CAAC;AAAA,EACxB,WAAW,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,SAAS;AACxC,CAAC;AAaM,IAAM,uBAAuB,EAAE,OAAO;AAAA,EAC3C,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC;AAAA,EACvB,IAAI,EAAE,KAAK,CAAC,MAAM,OAAO,MAAM,OAAO,MAAM,OAAO,MAAM,KAAK,CAAC;AAAA,EAC/D,OAAO,EAAE,QAAQ;AACnB,CAAC;AAQD,IAAM,6BAA6B,EAAE,OAAO;AAAA,EAC1C,MAAM,EAAE,QAAQ,gBAAgB;AAAA,EAChC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC;AACzB,CAAC;AAED,IAAM,uBAAuB,EAAE,OAAO;AAAA,EACpC,MAAM,EAAE,QAAQ,UAAU;AAAA,EAC1B,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC;AACzB,CAAC;AAED,IAAM,wBAAwB,EAAE,OAAO;AAAA,EACrC,MAAM,EAAE,QAAQ,WAAW;AAAA,EAC3B,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC;AACzB,CAAC;AAED,IAAM,sBAAsB,EAAE,OAAO;AAAA,EACnC,MAAM,EAAE,QAAQ,SAAS;AAAA,EACzB,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC;AACzB,CAAC;AAOD,IAAM,wBAAwB,EAAE,OAAO;AAAA,EACrC,MAAM,EAAE,QAAQ,WAAW;AAAA,EAC3B,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC;AACzB,CAAC;AAMD,IAAM,wBAAwB,EAAE,OAAO;AAAA,EACrC,MAAM,EAAE,QAAQ,WAAW;AAAA,EAC3B,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC;AACzB,CAAC;AAEM,IAAM,uBAAuB,EAAE,mBAAmB,QAAQ;AAAA,EAC/D;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAC;AAwBM,IAAM,sBAAyE;AAAA,EACpF,gBAAgB;AAAA,EAChB,WAAW;AAAA,EACX,UAAU;AAAA,EACV,SAAS;AAAA,EACT,WAAW;AAAA,EACX,WAAW;AACb;AAGO,SAAS,kBAAkB,MAAuC;AACvE,SAAO,oBAAoB,IAAI;AACjC;AAWO,IAAM,sBAAsB,EAAE,OAAO;AAAA,EAC1C,QAAQ;AAAA,EACR,YAAY,EAAE,KAAK,CAAC,QAAQ,KAAK,CAAC,EAAE,SAAS;AAC/C,CAAC;AASM,IAAM,yBAAyB,EAAE,OAAO;AAAA,EAC7C,cAAc,EAAE,OAAO,EAAE,IAAI,CAAC;AAChC,CAAC;AAQD,IAAM,iBAAiB,EAAE,OAAO;AAAA,EAC9B,MAAM,EAAE,QAAQ,MAAM;AAAA,EACtB,MAAM;AAAA,EACN,SAAS,EAAE,MAAM,kBAAkB,EAAE,IAAI,CAAC;AAAA,EAC1C,SAAS,EAAE,MAAM,oBAAoB,EAAE,QAAQ,CAAC,CAAC;AACnD,CAAC;AAED,IAAM,oBAAoB,EAAE,OAAO;AAAA,EACjC,MAAM,EAAE,QAAQ,SAAS;AAAA,EACzB,SAAS;AAAA,EACT,SAAS,EAAE,MAAM,kBAAkB,EAAE,IAAI,CAAC;AAAA,EAC1C,SAAS,EAAE,MAAM,oBAAoB,EAAE,QAAQ,CAAC,CAAC;AACnD,CAAC;AASM,IAAM,wBAAwB,EAAE,mBAAmB,QAAQ;AAAA,EAChE;AAAA,EACA;AACF,CAAC;","names":[]}

package/dist/chunk-YLPAPPLW.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../runtime/subsystems/integration/webhook-change-source.ts"],"sourcesContent":["/**\n * Integration subsystem — `WebhookChangeSource<T>` primitive (#226-4, ADR-033).\n *\n * Generic webhook-mode `IChangeSource<T>` implementation parameterized by a\n * parsed `DetectionConfig` (webhook mode) and a consumer-supplied\n * `WebhookFetchCallback<T>` that iterates a consumer-owned inbound staging\n * queue. The primitive owns:\n *\n *   - canonical `Change<T>.source = 'webhook'` stamping;\n *   - `dedupKey` derivation from the configured `webhook.eventIdField` on\n *     the emitted record;\n *   - `externalId` derivation: the mapping entry whose `target === 'external_id'`\n *     names — via its `source` — the field on the emitted record that carries\n *     the canonical external id (mirrors `PollChangeSource`);\n *   - middleware-chain composition via the locked `ChangeMiddleware<T>` shape\n *     (#226-1) — same composition seam as the poll primitive.\n *\n * The primitive is **passive**: it iterates whatever the consumer-owned\n * queue yields. It does NOT synchronously drive the orchestrator, does NOT\n * own a transport, and does NOT manage acks. The inbound staging table\n * schema is consumer-owned and deferred per ADR-0002 §Phase 4 — the\n * `WebhookFetchCallback<T>` is the queue contract the consumer injects.\n *\n * Shape locks (decision memo Q5, mirrored from poll primitive):\n *   - `WebhookFetchContext = { subscription, cursor }` — explicitly NO\n *     `userId` / `tenantId`. Run-scope identity is closed over by the\n *     consumer at queue construction or resolved inside the callback via\n *     consumer services. There are no `filters` on the webhook context —\n *     filtering is done at registration / on the staging row, not at the\n *     port seam (the queue is already filtered by the time the primitive\n *     iterates).\n *\n * Long-lived streaming CDC primitives (SFDC Pub-Sub gRPC, Debezium/Kafka,\n * Postgres logical replication) are deferred to `#226-8` — they need a\n * fundamentally different lifecycle (`subscribe(onChange, onError)`,\n * server-paced backpressure, ack-on-yield) and shouldn't be retrofitted\n * into either this primitive or the poll primitive.\n */\n\nimport type { DetectionConfig } from './detection-config.schema';\nimport type {\n  Change,\n  IChangeSource,\n  IntegrationSubscriptionView,\n} from './integration-change-source.protocol';\nimport type {\n  ChangeIterator,\n  ChangeMiddleware,\n} from './integration-middleware.protocol';\n\n// ============================================================================\n// Cursor + queue callback shapes\n// ============================================================================\n\n/**\n * Opaque webhook cursor shape. Webhook mode typically has a cursor of\n * `{ ts: ISO-string }` (last drained staging-row timestamp) but the\n * primitive treats it as opaque. Consumer-owned queue iterators interpret\n * it however the staging schema needs.\n */\nexport type WebhookCursor = unknown;\n\n/**\n * Context the primitive forwards to the queue iterator. Locked to exactly\n * two fields per the same Q5 reasoning that locks `PollFetchContext` — no\n * `userId` / `tenantId`.\n */\nexport interface WebhookFetchContext {\n  readonly subscription: IntegrationSubscriptionView;\n  readonly cursor: WebhookCursor | null;\n}\n\n/**\n * Consumer-supplied queue iterator. Returns an async iterable of\n * `{ record }` pairs — the consumer drains the inbound staging queue and\n * emits already-mapped canonical records `T`. The primitive stamps\n * `source: 'webhook'` and `dedupKey` from the record's configured\n * `webhook.eventIdField`; the consumer is the one who decided when a\n * staging row is \"ready\" to drain.\n *\n * Webhook mode has no per-record cursor advance — the staging-row drain\n * order is consumer policy (FIFO by ingestion timestamp, by event id, etc.)\n * and is opaque to the primitive. The orchestrator's last-yielded cursor\n * is whatever the consumer chooses to surface, if anything.\n */\nexport type WebhookFetchCallback<T> = (\n  ctx: WebhookFetchContext,\n) => AsyncIterable<{ record: T; cursor?: WebhookCursor }>;\n\n// ============================================================================\n// Constructor options\n// ============================================================================\n\nexport interface WebhookChangeSourceOptions<T> {\n  /** Consumer-supplied inbound queue iterator. */\n  readonly queue: WebhookFetchCallback<T>;\n  /**\n   * Parsed detection config. MUST be `mode: 'webhook'`; the constructor\n   * throws if a poll config is supplied. Codegen-emitted factories call\n   * `DetectionConfigSchema.parse(...)` upstream so this is a safety net,\n   * not the primary validation point.\n   */\n  readonly config: DetectionConfig;\n  /**\n   * Optional middleware chain. Same shape and composition rules as\n   * `PollChangeSource` — first element is the outermost layer.\n   */\n  readonly middlewares?: ReadonlyArray<ChangeMiddleware<T>>;\n  /**\n   * Optional human label for run logs (e.g. `'stripe-webhook-charge'`).\n   * Defaults to a derived label based on the mapping at construction.\n   */\n  readonly label?: string;\n}\n\n// ============================================================================\n// WebhookChangeSource<T>\n// ============================================================================\n\nexport class WebhookChangeSource<T> implements IChangeSource<T> {\n  public readonly label: string;\n\n  private readonly queue: WebhookFetchCallback<T>;\n  private readonly externalIdSourceField: string;\n  private readonly eventIdSourceField: string;\n  private readonly composed: ChangeIterator<T>;\n\n  constructor(opts: WebhookChangeSourceOptions<T>) {\n    if (opts.config.mode !== 'webhook') {\n      throw new Error(\n        `WebhookChangeSource requires DetectionConfig.mode === 'webhook'; got '${(opts.config as { mode: string }).mode}'`,\n      );\n    }\n    const config = opts.config;\n\n    // Field mapping: locate the entry whose canonical `target` is `external_id`\n    // — mirrors the poll primitive's contract. Adapters emit records\n    // already-mapped; the primitive needs to know which key on T carries the\n    // external id so it can stamp `Change.externalId`. That key is the\n    // mapping's `source` (the field on the emitted record), NOT its `target`\n    // (the canonical column) — they differ whenever the canonical record is\n    // vendor-neutral camelCase (e.g. `source: 'externalId'` → `target: 'external_id'`).\n    const externalIdMapping = config.mapping.find(\n      (m) => m.target === 'external_id',\n    );\n    if (!externalIdMapping) {\n      throw new Error(\n        \"WebhookChangeSource: DetectionConfig.mapping must include an entry with target 'external_id' so emitted Change<T>.externalId can be populated\",\n      );\n    }\n    this.externalIdSourceField = externalIdMapping.source;\n    this.eventIdSourceField = config.webhook.eventIdField;\n\n    this.queue = opts.queue;\n\n    this.label =\n      opts.label ?? `webhook-change-source:${externalIdMapping.source}`;\n\n    // Compose middleware chain — same shape as PollChangeSource.\n    const inner: ChangeIterator<T> = (sub, cur) => this.fetch(sub, cur);\n    const middlewares = opts.middlewares ?? [];\n    this.composed = middlewares.reduceRight<ChangeIterator<T>>(\n      (next, mw) => mw(next),\n      inner,\n    );\n  }\n\n  listChanges(\n    subscription: IntegrationSubscriptionView,\n    cursor: unknown | null,\n  ): AsyncIterable<Change<T>> {\n    return this.composed(subscription, cursor);\n  }\n\n  private async *fetch(\n    subscription: IntegrationSubscriptionView,\n    cursor: unknown | null,\n  ): AsyncIterable<Change<T>> {\n    const ctx: WebhookFetchContext = {\n      subscription,\n      cursor: cursor as WebhookCursor | null,\n    };\n\n    for await (const { record, cursor: nextCursor } of this.queue(ctx)) {\n      const externalIdRaw = (record as Record<string, unknown>)[\n        this.externalIdSourceField\n      ];\n      if (typeof externalIdRaw !== 'string' || externalIdRaw.length === 0) {\n        throw new Error(\n          `WebhookChangeSource: record missing string '${this.externalIdSourceField}' — emitted records MUST carry the canonical external id keyed by the mapping source`,\n        );\n      }\n      const eventIdRaw = (record as Record<string, unknown>)[\n        this.eventIdSourceField\n      ];\n      if (typeof eventIdRaw !== 'string' || eventIdRaw.length === 0) {\n        throw new Error(\n          `WebhookChangeSource: record missing string '${this.eventIdSourceField}' — webhook records MUST carry the event id (DetectionConfig.webhook.eventIdField) so Change<T>.dedupKey can be populated`,\n        );\n      }\n\n      const change: Change<T> = {\n        externalId: externalIdRaw,\n        // Webhook mode cannot distinguish create vs. update vs. delete on\n        // its own — the orchestrator's diff stage handles classification.\n        // Tombstone / soft-delete detection is consumer-driven (same as\n        // poll mode — see ADR-033).\n        operation: 'updated',\n        record,\n        cursor: nextCursor ?? null,\n        source: 'webhook',\n        dedupKey: eventIdRaw,\n      };\n      yield change;\n    }\n  }\n}\n"],"mappings":";AAuHO,IAAM,sBAAN,MAAyD;AAAA,EAC9C;AAAA,EAEC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAEjB,YAAY,MAAqC;AAC/C,QAAI,KAAK,OAAO,SAAS,WAAW;AAClC,YAAM,IAAI;AAAA,QACR,yEAA0E,KAAK,OAA4B,IAAI;AAAA,MACjH;AAAA,IACF;AACA,UAAM,SAAS,KAAK;AASpB,UAAM,oBAAoB,OAAO,QAAQ;AAAA,MACvC,CAAC,MAAM,EAAE,WAAW;AAAA,IACtB;AACA,QAAI,CAAC,mBAAmB;AACtB,YAAM,IAAI;AAAA,QACR;AAAA,MACF;AAAA,IACF;AACA,SAAK,wBAAwB,kBAAkB;AAC/C,SAAK,qBAAqB,OAAO,QAAQ;AAEzC,SAAK,QAAQ,KAAK;AAElB,SAAK,QACH,KAAK,SAAS,yBAAyB,kBAAkB,MAAM;AAGjE,UAAM,QAA2B,CAAC,KAAK,QAAQ,KAAK,MAAM,KAAK,GAAG;AAClE,UAAM,cAAc,KAAK,eAAe,CAAC;AACzC,SAAK,WAAW,YAAY;AAAA,MAC1B,CAAC,MAAM,OAAO,GAAG,IAAI;AAAA,MACrB;AAAA,IACF;AAAA,EACF;AAAA,EAEA,YACE,cACA,QAC0B;AAC1B,WAAO,KAAK,SAAS,cAAc,MAAM;AAAA,EAC3C;AAAA,EAEA,OAAe,MACb,cACA,QAC0B;AAC1B,UAAM,MAA2B;AAAA,MAC/B;AAAA,MACA;AAAA,IACF;AAEA,qBAAiB,EAAE,QAAQ,QAAQ,WAAW,KAAK,KAAK,MAAM,GAAG,GAAG;AAClE,YAAM,gBAAiB,OACrB,KAAK,qBACP;AACA,UAAI,OAAO,kBAAkB,YAAY,cAAc,WAAW,GAAG;AACnE,cAAM,IAAI;AAAA,UACR,+CAA+C,KAAK,qBAAqB;AAAA,QAC3E;AAAA,MACF;AACA,YAAM,aAAc,OAClB,KAAK,kBACP;AACA,UAAI,OAAO,eAAe,YAAY,WAAW,WAAW,GAAG;AAC7D,cAAM,IAAI;AAAA,UACR,+CAA+C,KAAK,kBAAkB;AAAA,QACxE;AAAA,MACF;AAEA,YAAM,SAAoB;AAAA,QACxB,YAAY;AAAA;AAAA;AAAA;AAAA;AAAA,QAKZ,WAAW;AAAA,QACX;AAAA,QACA,QAAQ,cAAc;AAAA,QACtB,QAAQ;AAAA,QACR,UAAU;AAAA,MACZ;AACA,YAAM;AAAA,IACR;AAAA,EACF;AACF;","names":[]}