@pattern-stack/codegen 0.12.2 → 0.13.1

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

@@ -102,8 +102,45 @@ declare const CursorStrategySchema: z.ZodDiscriminatedUnion<"kind", [z.ZodObject
 }, {
     field: string;
     kind: "eventId";
+}>, z.ZodObject<{
+    kind: z.ZodLiteral<"historyId">;
+    field: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    field: string;
+    kind: "historyId";
+}, {
+    field: string;
+    kind: "historyId";
+}>, z.ZodObject<{
+    kind: z.ZodLiteral<"syncToken">;
+    field: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    field: string;
+    kind: "syncToken";
+}, {
+    field: string;
+    kind: "syncToken";
 }>]>;
 type CursorStrategy = z.infer<typeof CursorStrategySchema>;
+/**
+ * Whether a cursor strategy is *divisible* — a property of the strategy, not
+ * the read primitive. Divisible cursors are sortable/monotonic watermarks whose
+ * value is meaningful AS OF any single record (HubSpot `systemModstamp`, a
+ * `timestamp` field, a Salesforce CDC `replayId`); the read primitive may
+ * checkpoint per-ref mid-walk, so a crash resumes from the last delivered ref.
+ *
+ * Atomic cursors are opaque vendor tokens (Gmail `historyId`, Calendar
+ * `syncToken`, a generic `eventId`) whose next value only exists at end-of-walk.
+ * The primitive must withhold per-ref cursors and emit the token only at a safe
+ * boundary, so an interrupted run never persists an unresumable mid-walk token
+ * (it resumes all-or-nothing from the prior token — see `IncrementalReadBase`).
+ *
+ * `eventId` is classified atomic conservatively: a generic opaque id is treated
+ * all-or-nothing unless a concrete strategy proves it monotonically resumable.
+ */
+declare const CURSOR_DIVISIBILITY: Readonly<Record<CursorStrategy['kind'], boolean>>;
+/** Predicate form of {@link CURSOR_DIVISIBILITY}. */
+declare function isDivisibleCursor(kind: CursorStrategy['kind']): boolean;
 /**
  * Poll-mode block. `provenance: 'cdc'` opts the poll primitive into stamping
  * `Change<T>.source = 'cdc'` and populating `dedupKey` from the cursor's
@@ -146,6 +183,24 @@ declare const PollDetectionSchema: z.ZodObject<{
     }, {
         field: string;
         kind: "eventId";
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"historyId">;
+        field: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        field: string;
+        kind: "historyId";
+    }, {
+        field: string;
+        kind: "historyId";
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"syncToken">;
+        field: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        field: string;
+        kind: "syncToken";
+    }, {
+        field: string;
+        kind: "syncToken";
     }>]>;
     provenance: z.ZodOptional<z.ZodEnum<["poll", "cdc"]>>;
 }, "strip", z.ZodTypeAny, {
@@ -161,6 +216,12 @@ declare const PollDetectionSchema: z.ZodObject<{
     } | {
         field: string;
         kind: "eventId";
+    } | {
+        field: string;
+        kind: "historyId";
+    } | {
+        field: string;
+        kind: "syncToken";
     };
     provenance?: "poll" | "cdc" | undefined;
 }, {
@@ -176,6 +237,12 @@ declare const PollDetectionSchema: z.ZodObject<{
     } | {
         field: string;
         kind: "eventId";
+    } | {
+        field: string;
+        kind: "historyId";
+    } | {
+        field: string;
+        kind: "syncToken";
     };
     provenance?: "poll" | "cdc" | undefined;
 }>;
@@ -239,6 +306,24 @@ declare const DetectionConfigSchema: z.ZodDiscriminatedUnion<"mode", [z.ZodObjec
         }, {
             field: string;
             kind: "eventId";
+        }>, z.ZodObject<{
+            kind: z.ZodLiteral<"historyId">;
+            field: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            field: string;
+            kind: "historyId";
+        }, {
+            field: string;
+            kind: "historyId";
+        }>, z.ZodObject<{
+            kind: z.ZodLiteral<"syncToken">;
+            field: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            field: string;
+            kind: "syncToken";
+        }, {
+            field: string;
+            kind: "syncToken";
         }>]>;
         provenance: z.ZodOptional<z.ZodEnum<["poll", "cdc"]>>;
     }, "strip", z.ZodTypeAny, {
@@ -254,6 +339,12 @@ declare const DetectionConfigSchema: z.ZodDiscriminatedUnion<"mode", [z.ZodObjec
         } | {
             field: string;
             kind: "eventId";
+        } | {
+            field: string;
+            kind: "historyId";
+        } | {
+            field: string;
+            kind: "syncToken";
         };
         provenance?: "poll" | "cdc" | undefined;
     }, {
@@ -269,6 +360,12 @@ declare const DetectionConfigSchema: z.ZodDiscriminatedUnion<"mode", [z.ZodObjec
         } | {
             field: string;
             kind: "eventId";
+        } | {
+            field: string;
+            kind: "historyId";
+        } | {
+            field: string;
+            kind: "syncToken";
         };
         provenance?: "poll" | "cdc" | undefined;
     }>;
@@ -312,6 +409,12 @@ declare const DetectionConfigSchema: z.ZodDiscriminatedUnion<"mode", [z.ZodObjec
         } | {
             field: string;
             kind: "eventId";
+        } | {
+            field: string;
+            kind: "historyId";
+        } | {
+            field: string;
+            kind: "syncToken";
         };
         provenance?: "poll" | "cdc" | undefined;
     };
@@ -340,6 +443,12 @@ declare const DetectionConfigSchema: z.ZodDiscriminatedUnion<"mode", [z.ZodObjec
         } | {
             field: string;
             kind: "eventId";
+        } | {
+            field: string;
+            kind: "historyId";
+        } | {
+            field: string;
+            kind: "syncToken";
         };
         provenance?: "poll" | "cdc" | undefined;
     };
@@ -422,4 +531,4 @@ declare const DetectionConfigSchema: z.ZodDiscriminatedUnion<"mode", [z.ZodObjec
 }>]>;
 type DetectionConfig = z.infer<typeof DetectionConfigSchema>;
 
-export { type CursorStrategy, CursorStrategySchema, type DetectionConfig, DetectionConfigSchema, type FieldMapping, FieldMappingSchema, type PollDetection, PollDetectionSchema, type ResolvedFilter, ResolvedFilterSchema, type WebhookDetection, WebhookDetectionSchema };
+export { CURSOR_DIVISIBILITY, type CursorStrategy, CursorStrategySchema, type DetectionConfig, DetectionConfigSchema, type FieldMapping, FieldMappingSchema, type PollDetection, PollDetectionSchema, type ResolvedFilter, ResolvedFilterSchema, type WebhookDetection, WebhookDetectionSchema, isDivisibleCursor };

package/dist/runtime/subsystems/integration/detection-config.schema.js

@@ -26,12 +26,33 @@ var EventIdCursorSchema = z.object({
   kind: z.literal("eventId"),
   field: z.string().min(1)
 });
+var HistoryIdCursorSchema = z.object({
+  kind: z.literal("historyId"),
+  field: z.string().min(1)
+});
+var SyncTokenCursorSchema = z.object({
+  kind: z.literal("syncToken"),
+  field: z.string().min(1)
+});
 var CursorStrategySchema = z.discriminatedUnion("kind", [
   SystemModstampCursorSchema,
   ReplayIdCursorSchema,
   TimestampCursorSchema,
-  EventIdCursorSchema
+  EventIdCursorSchema,
+  HistoryIdCursorSchema,
+  SyncTokenCursorSchema
 ]);
+var CURSOR_DIVISIBILITY = {
+  systemModstamp: true,
+  timestamp: true,
+  replayId: true,
+  eventId: false,
+  historyId: false,
+  syncToken: false
+};
+function isDivisibleCursor(kind) {
+  return CURSOR_DIVISIBILITY[kind];
+}
 var PollDetectionSchema = z.object({
   cursor: CursorStrategySchema,
   provenance: z.enum(["poll", "cdc"]).optional()
@@ -56,11 +77,13 @@ var DetectionConfigSchema = z.discriminatedUnion("mode", [
   WebhookModeSchema
 ]);
 export {
+  CURSOR_DIVISIBILITY,
   CursorStrategySchema,
   DetectionConfigSchema,
   FieldMappingSchema,
   PollDetectionSchema,
   ResolvedFilterSchema,
-  WebhookDetectionSchema
+  WebhookDetectionSchema,
+  isDivisibleCursor
 };
 //# sourceMappingURL=detection-config.schema.js.map

package/dist/runtime/subsystems/integration/detection-config.schema.js.map

@@ -1 +1 @@
-{"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\nexport const CursorStrategySchema = z.discriminatedUnion('kind', [\n  SystemModstampCursorSchema,\n  ReplayIdCursorSchema,\n  TimestampCursorSchema,\n  EventIdCursorSchema,\n]);\n\nexport type CursorStrategy = z.infer<typeof CursorStrategySchema>;\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;AAEM,IAAM,uBAAuB,EAAE,mBAAmB,QAAQ;AAAA,EAC/D;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAC;AAaM,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":[]}
+{"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/runtime/subsystems/integration/incremental-read.d.ts

@@ -0,0 +1,248 @@
+import { IntegrationSubscriptionView, IChangeSource, ChangeSource, Change } from './integration-change-source.protocol.js';
+
+/**
+ * Integration subsystem — `IncrementalRead<T, F>` + `RandomRead<T>` capability
+ * and the providing `IncrementalReadBase<T, F, M>` (RFC-0003 R1).
+ *
+ * The universal read primitive. Where `IChangeSource.listChanges` is the
+ * *transport* contract (stream `Change<T>`, orchestrator owns cursor lifecycle),
+ * this base owns *how the body that produces those changes is written* — the
+ * level the bare `changeSources = {}` author-seam left unstructured.
+ *
+ * The read decomposes into two composable verbs the adapter supplies:
+ *
+ *   - `enumerate(mode, filter) → AsyncIterable<Ref<M>[]>` — the cheap delta /
+ *     backfill walk; streams pages of lightweight refs (id + per-ref cursor +
+ *     filterable metadata). LAZY: pull-driven so hydrate backpressures it.
+ *   - `hydrate(ids) → Map<id, raw>` — the expensive fetch-by-id, batched; where
+ *     bounded concurrency / a vendor `/batch` endpoint lives. Keyed and
+ *     miss-tolerant (a mid-run 404 cannot shift alignment).
+ *   - `toCanonical(raw) → T | null` — provider payload → canonical record.
+ *
+ * The base PROVIDES the orchestration: drain enumerate, **filter before
+ * hydrate** (structural — an adapter physically cannot hydrate-then-discard),
+ * keyed pairing, per-ref cursor emission, and the `IChangeSource.listChanges`
+ * adaptation. It also provides `RandomRead.get()` for free as
+ * `toCanonical ∘ hydrate([id])` — so every incremental adapter is a
+ * single-record reader (the "list cheaply, fill on click" query-surface need)
+ * without extra code.
+ *
+ * The shape generalizes dealbrain's proven HubSpot `listSince` (streams, pushes
+ * the filter server-side, carries a per-record cursor) to vendors whose list
+ * returns id-stubs (Gmail) or nested resources (Meet). Calendar-style
+ * full-object lists override `hydrate` as a passthrough.
+ *
+ * See RFC-0003 (Track D round-3), ADR-033 (`detection:` config), and
+ * `poll-change-source.ts` (the sibling primitive this composes beside).
+ */
+
+/**
+ * How a read walks the upstream. Modes are values, not verbs (swe-brain
+ * ADR-0003: mode ≠ capability) — one `read()` verb dispatches on these.
+ *
+ *   - `delta`     — incremental walk from a persisted cursor.
+ *   - `full`      — cursorless backfill (optionally bounded by `since`).
+ *   - `reconcile` — gap-repair: re-fetch a known id set the cursor skipped
+ *                   (the repair pass for the silent-tail-skip + #414-style
+ *                   multi-provider divergence).
+ */
+type ReadMode = {
+    readonly kind: 'delta';
+    readonly cursor: unknown;
+} | {
+    readonly kind: 'full';
+    readonly since?: Date;
+} | {
+    readonly kind: 'reconcile';
+    readonly knownIds: readonly string[];
+};
+/**
+ * A cheap ref from the enumerate pass: identity + per-ref cursor + metadata to
+ * filter or display on. `cursor` is the position AS OF this ref — see
+ * `IncrementalReadBase.cursorDivisible` (R2) for when it may be checkpointed
+ * mid-walk versus withheld until a safe boundary.
+ */
+interface Ref<M = Record<string, unknown>> {
+    readonly externalId: string;
+    readonly cursor: unknown;
+    readonly meta: M;
+}
+/** A read request: the mode, an optional adapter-typed filter, and page size. */
+interface ReadRequest<F = unknown> {
+    readonly mode: ReadMode;
+    readonly filter?: F;
+    readonly pageSize?: number;
+}
+/**
+ * Per-run context threaded from `listChanges` into the vendor read body (R5).
+ *
+ * Carries the `subscription` framing the run so `enumerate`/`hydrate` can resolve
+ * **per-connection credentials** (and raw-landing keys) from
+ * `subscription.externalRef` — the gap a multi-account consumer surfaced: a
+ * singleton change source cannot hold connection-scoped auth, and before R5 the
+ * base forwarded the subscription only into `filterFor`, never into the fetch.
+ *
+ * Optional throughout (the core contract): a direct `read()` / `get()` call — the
+ * query surface's "fill one record on click" — may omit it. An adapter that needs
+ * per-connection auth reads `ctx?.subscription?.externalRef` and asserts its
+ * presence; a provider-level-auth adapter ignores it.
+ */
+interface ReadContext {
+    /** The subscription framing this run; `externalRef` is the upstream scope /
+     *  connection id the adapter resolves credentials + raw-landing keys from. */
+    readonly subscription?: IntegrationSubscriptionView;
+}
+/**
+ * The `read()`-side envelope: canonical record + the raw vendor payload it came
+ * from + the originating external id + the per-ref cursor.
+ *
+ * Distinct from the runtime's transport envelope `Change<T>`
+ * (operation/externalId/cursor/source). The relationship is one-directional:
+ * `listChanges()` adapts `read()` → `Change<T>` (dropping `raw`, stamping
+ * `operation`). `read()` keeps `raw` and `externalId` so a query surface can
+ * re-project without a second fetch.
+ */
+interface SourcedRecord<T> {
+    readonly externalId: string;
+    readonly record: T;
+    readonly raw: unknown;
+    readonly cursor: unknown;
+}
+/**
+ * The universal read capability — one public verb that streams. Filtering,
+ * hydration, and cursor emission are the providing base's concern.
+ */
+interface IncrementalRead<T, F = unknown> {
+    read(req: ReadRequest<F>, ctx?: ReadContext): AsyncIterable<SourcedRecord<T>>;
+}
+/**
+ * Single-record read by external id — the "fill on click" atom. Provided for
+ * free by `IncrementalReadBase` (composes `hydrate` + `toCanonical`); declared
+ * as its own capability so consumers can depend on it without the streaming
+ * surface.
+ */
+interface RandomRead<T> {
+    get(id: string, ctx?: ReadContext): Promise<T | null>;
+}
+/**
+ * Map `ids` through `fn` with at most `limit` concurrent in-flight calls,
+ * collecting results keyed by id. The workhorse for writing a batched
+ * `hydrate` over a single-id fetch without serial N+1 latency.
+ */
+declare function mapConcurrent<R>(ids: readonly string[], fn: (id: string) => Promise<R>, limit: number): Promise<Map<string, R>>;
+/**
+ * Providing base for the read capability. A subclass fills exactly three vendor
+ * methods — `enumerate`, `hydrate`, `toCanonical` — and gets a streaming,
+ * filter-before-hydrate, miss-tolerant `IncrementalRead<T, F>` +
+ * `IChangeSource<T>` + `RandomRead<T>`.
+ *
+ * Type params: `T` canonical record, `F` adapter-typed filter, `M` per-ref
+ * metadata (defaults to an untyped bag — surface packages supply a domain `M`).
+ */
+declare abstract class IncrementalReadBase<T, F = unknown, M = Record<string, unknown>> implements IncrementalRead<T, F>, IChangeSource<T>, RandomRead<T> {
+    /** Human label for run logs — e.g. `'google-mail-email'`. */
+    abstract readonly label: string;
+    /**
+     * Whether the vendor takes the request predicate server-side. Declared, not
+     * enforced here — surfaced into the emission manifest (R3) so the falsifier
+     * suite (R4) can record which adapters filter post-hydrate. `false` is the
+     * honest floor (e.g. Gmail without `q=`), handled via `matchesRecord`.
+     */
+    protected readonly filterPushdown: boolean;
+    /** Max concurrent in-flight calls for a `mapConcurrent`-built `hydrate`. */
+    protected readonly hydrateConcurrency: number;
+    /** `Change<T>.source` provenance stamped by `listChanges`. */
+    protected readonly changeSource: ChangeSource;
+    /**
+     * Whether this source's cursor strategy is divisible (RFC-0003 §3). When
+     * `true` (default — sortable watermarks like `systemModstamp`/`timestamp`/
+     * `replayId`), `listChanges` emits each record's per-ref cursor, so the
+     * orchestrator may checkpoint mid-walk and a crash resumes from the last
+     * delivered ref.
+     *
+     * When `false` (atomic opaque tokens — Gmail `historyId`, Calendar
+     * `syncToken`), `listChanges` WITHHOLDS per-ref cursors and emits the
+     * end-of-walk token only on the final record, so the orchestrator's
+     * persist-last-yielded lifecycle can never persist an unresumable mid-walk
+     * token. The cost is blast-radius: an interrupted atomic run resumes
+     * all-or-nothing from the prior persisted token. For atomic *backfills* that
+     * radius is the whole enumerate walk — bound it with `ReadRequest.pageSize`
+     * (smaller pages ⇒ shorter walks per run). Per-page atomic checkpointing is a
+     * future refinement; R2 gates at end-of-walk.
+     *
+     * Codegen (R3) sets this from the strategy kind via `isDivisibleCursor`.
+     */
+    protected readonly cursorDivisible: boolean;
+    /**
+     * The cheap walk. Streams pages of refs; LAZY so `hydrate` backpressures it
+     * (one page hydrated before the next is pulled). Mode-dispatch lives here:
+     * `delta` resumes from `mode.cursor`, `full` walks from the top, `reconcile`
+     * re-fetches `mode.knownIds`.
+     *
+     * `pageSize` (from `ReadRequest`) is the adapter's requested vendor page size
+     * — also the atomic-cursor backfill blast-radius bound (§ `cursorDivisible`).
+     * Honor it as a hint; vendors that cap page size clamp it.
+     *
+     * `ctx?.subscription` (R5) carries the run's subscription, so a per-connection
+     * adapter resolves credentials / upstream scope from `externalRef` here; absent
+     * on a direct `read()` with no run subscription.
+     */
+    protected abstract enumerate(mode: ReadMode, filter?: F, pageSize?: number, ctx?: ReadContext): AsyncIterable<Ref<M>[]>;
+    /**
+     * Fetch raw payloads for `ids`, keyed by id. MUST be miss-tolerant: omit (or
+     * map to `null`) any id that 404s mid-run rather than throwing or shifting
+     * alignment. Write it over `mapConcurrent(ids, (id) => this.fetchOne(id),
+     * this.hydrateConcurrency)`; override with a real `/batch` call or a
+     * passthrough (full-object list) where the vendor allows.
+     *
+     * `ctx?.subscription` (R5) carries the run's subscription for per-connection
+     * credential resolution (the fetch is where the vendor call happens) and is the
+     * natural place to land raw payloads keyed by `subscription.id`.
+     */
+    protected abstract hydrate(ids: string[], ctx?: ReadContext): Promise<Map<string, unknown>>;
+    /** Provider payload → canonical record. Return `null` to drop a record. */
+    protected abstract toCanonical(raw: unknown): T | null;
+    /** Pre-hydrate predicate over the cheap ref (preferred — avoids hydration). */
+    protected matchesRef(_ref: Ref<M>, _filter?: F): boolean;
+    /** Post-hydrate predicate over the canonical record (the no-pushdown floor). */
+    protected matchesRecord(_record: T, _filter?: F): boolean;
+    /**
+     * Resolve the filter for a subscription when adapting to `listChanges`
+     * (which has no filter argument). Defaults to none; codegen wiring (R3)
+     * overrides this to thread `DetectionConfig.filters`.
+     */
+    protected filterFor(_subscription: IntegrationSubscriptionView): F | undefined;
+    /**
+     * Stream canonical records for a request. Filter is applied BEFORE hydrate
+     * (structural: a kept ref is hydrated, a rejected one never is), so an
+     * adapter cannot hydrate-then-discard. A hydrate miss (deleted mid-run) is
+     * skipped, never fabricated.
+     */
+    read(req: ReadRequest<F>, ctx?: ReadContext): AsyncIterable<SourcedRecord<T>>;
+    /**
+     * `RandomRead<T>` — single-record read, provided for free as
+     * `toCanonical ∘ hydrate([id])`. Reuses the adapter's batched fetch + miss
+     * tolerance; returns `null` for a missing or undecodable record.
+     */
+    get(id: string, ctx?: ReadContext): Promise<T | null>;
+    /**
+     * `IChangeSource<T>` adaptation. Maps the orchestrator's by-value cursor to a
+     * `ReadMode` (`null` → `full` backfill, else `delta`), streams `read()`, and
+     * stamps each `SourcedRecord` into a `Change<T>`. All records surface as
+     * `'updated'`; the orchestrator's diff stage classifies create-vs-update and
+     * deletes arrive as tombstone refs (`toCanonical` may flag them).
+     *
+     * Cursor emission honors `cursorDivisible` (RFC-0003 §3). Divisible: each
+     * record carries its own per-ref cursor. Atomic: per-ref cursors are withheld
+     * (`undefined`, which the orchestrator skips persisting) and the end-of-walk
+     * token rides only on the final record — so a mid-walk crash never persists
+     * an unresumable token. If an atomic run yields no surviving records, no
+     * cursor is persisted and the next run re-reads the same (empty) delta — a
+     * bounded inefficiency, never data loss.
+     */
+    listChanges(subscription: IntegrationSubscriptionView, cursor: unknown | null): AsyncIterable<Change<T>>;
+    /** Stamp a `SourcedRecord` into a `Change<T>` with an explicit emitted cursor. */
+    private toChange;
+}
+
+export { type IncrementalRead, IncrementalReadBase, type RandomRead, type ReadContext, type ReadMode, type ReadRequest, type Ref, type SourcedRecord, mapConcurrent };

package/dist/runtime/subsystems/integration/incremental-read.js

@@ -0,0 +1,149 @@
+// runtime/subsystems/integration/incremental-read.ts
+async function mapConcurrent(ids, fn, limit) {
+  const out = /* @__PURE__ */ new Map();
+  if (ids.length === 0) return out;
+  const width = Math.max(1, Math.min(limit, ids.length));
+  let next = 0;
+  const worker = async () => {
+    while (next < ids.length) {
+      const idx = next++;
+      const id = ids[idx];
+      out.set(id, await fn(id));
+    }
+  };
+  await Promise.all(Array.from({ length: width }, worker));
+  return out;
+}
+var IncrementalReadBase = class {
+  /**
+   * Whether the vendor takes the request predicate server-side. Declared, not
+   * enforced here — surfaced into the emission manifest (R3) so the falsifier
+   * suite (R4) can record which adapters filter post-hydrate. `false` is the
+   * honest floor (e.g. Gmail without `q=`), handled via `matchesRecord`.
+   */
+  filterPushdown = false;
+  /** Max concurrent in-flight calls for a `mapConcurrent`-built `hydrate`. */
+  hydrateConcurrency = 10;
+  /** `Change<T>.source` provenance stamped by `listChanges`. */
+  changeSource = "poll";
+  /**
+   * Whether this source's cursor strategy is divisible (RFC-0003 §3). When
+   * `true` (default — sortable watermarks like `systemModstamp`/`timestamp`/
+   * `replayId`), `listChanges` emits each record's per-ref cursor, so the
+   * orchestrator may checkpoint mid-walk and a crash resumes from the last
+   * delivered ref.
+   *
+   * When `false` (atomic opaque tokens — Gmail `historyId`, Calendar
+   * `syncToken`), `listChanges` WITHHOLDS per-ref cursors and emits the
+   * end-of-walk token only on the final record, so the orchestrator's
+   * persist-last-yielded lifecycle can never persist an unresumable mid-walk
+   * token. The cost is blast-radius: an interrupted atomic run resumes
+   * all-or-nothing from the prior persisted token. For atomic *backfills* that
+   * radius is the whole enumerate walk — bound it with `ReadRequest.pageSize`
+   * (smaller pages ⇒ shorter walks per run). Per-page atomic checkpointing is a
+   * future refinement; R2 gates at end-of-walk.
+   *
+   * Codegen (R3) sets this from the strategy kind via `isDivisibleCursor`.
+   */
+  cursorDivisible = true;
+  // ---- Optional filter hooks — exactly one is live per `filterPushdown` ----
+  /** Pre-hydrate predicate over the cheap ref (preferred — avoids hydration). */
+  matchesRef(_ref, _filter) {
+    return true;
+  }
+  /** Post-hydrate predicate over the canonical record (the no-pushdown floor). */
+  matchesRecord(_record, _filter) {
+    return true;
+  }
+  /**
+   * Resolve the filter for a subscription when adapting to `listChanges`
+   * (which has no filter argument). Defaults to none; codegen wiring (R3)
+   * overrides this to thread `DetectionConfig.filters`.
+   */
+  filterFor(_subscription) {
+    return void 0;
+  }
+  // ---- PROVIDED by the base ----
+  /**
+   * Stream canonical records for a request. Filter is applied BEFORE hydrate
+   * (structural: a kept ref is hydrated, a rejected one never is), so an
+   * adapter cannot hydrate-then-discard. A hydrate miss (deleted mid-run) is
+   * skipped, never fabricated.
+   */
+  async *read(req, ctx) {
+    for await (const refPage of this.enumerate(req.mode, req.filter, req.pageSize, ctx)) {
+      const kept = refPage.filter((ref) => this.matchesRef(ref, req.filter));
+      if (kept.length === 0) continue;
+      const raws = await this.hydrate(
+        kept.map((ref) => ref.externalId),
+        ctx
+      );
+      for (const ref of kept) {
+        const raw = raws.get(ref.externalId);
+        if (raw === void 0 || raw === null) continue;
+        const record = this.toCanonical(raw);
+        if (record !== null && this.matchesRecord(record, req.filter)) {
+          yield { externalId: ref.externalId, record, raw, cursor: ref.cursor };
+        }
+      }
+    }
+  }
+  /**
+   * `RandomRead<T>` — single-record read, provided for free as
+   * `toCanonical ∘ hydrate([id])`. Reuses the adapter's batched fetch + miss
+   * tolerance; returns `null` for a missing or undecodable record.
+   */
+  async get(id, ctx) {
+    const raws = await this.hydrate([id], ctx);
+    const raw = raws.get(id);
+    if (raw === void 0 || raw === null) return null;
+    return this.toCanonical(raw);
+  }
+  /**
+   * `IChangeSource<T>` adaptation. Maps the orchestrator's by-value cursor to a
+   * `ReadMode` (`null` → `full` backfill, else `delta`), streams `read()`, and
+   * stamps each `SourcedRecord` into a `Change<T>`. All records surface as
+   * `'updated'`; the orchestrator's diff stage classifies create-vs-update and
+   * deletes arrive as tombstone refs (`toCanonical` may flag them).
+   *
+   * Cursor emission honors `cursorDivisible` (RFC-0003 §3). Divisible: each
+   * record carries its own per-ref cursor. Atomic: per-ref cursors are withheld
+   * (`undefined`, which the orchestrator skips persisting) and the end-of-walk
+   * token rides only on the final record — so a mid-walk crash never persists
+   * an unresumable token. If an atomic run yields no surviving records, no
+   * cursor is persisted and the next run re-reads the same (empty) delta — a
+   * bounded inefficiency, never data loss.
+   */
+  async *listChanges(subscription, cursor) {
+    const mode = cursor === null || cursor === void 0 ? { kind: "full" } : { kind: "delta", cursor };
+    const filter = this.filterFor(subscription);
+    const stream = this.read({ mode, filter }, { subscription });
+    if (this.cursorDivisible) {
+      for await (const sourced of stream) {
+        yield this.toChange(sourced, sourced.cursor);
+      }
+      return;
+    }
+    let prev = null;
+    for await (const sourced of stream) {
+      if (prev !== null) yield this.toChange(prev, void 0);
+      prev = sourced;
+    }
+    if (prev !== null) yield this.toChange(prev, prev.cursor);
+  }
+  /** Stamp a `SourcedRecord` into a `Change<T>` with an explicit emitted cursor. */
+  toChange(sourced, cursor) {
+    return {
+      externalId: sourced.externalId,
+      operation: "updated",
+      record: sourced.record,
+      cursor,
+      source: this.changeSource
+    };
+  }
+};
+export {
+  IncrementalReadBase,
+  mapConcurrent
+};
+//# sourceMappingURL=incremental-read.js.map