graphddb 0.5.0 → 0.5.1

package/dist/{types-B-F7jw9f.d.ts → types-B9rJ1z3H.d.ts}

@@ -5992,6 +5992,189 @@ type MutateParallelResult<E extends WriteEnvelope> = {
     readonly [K in keyof E]: BulkWrap<E[K], ParallelResultOf<E[K]>>;
 };
 
+/**
+ * CDC emulator types (issue #72). These types are **cdc-module-owned**; core
+ * never references them. The {@link ChangeEvent} shape mirrors DynamoDB Streams
+ * (`NEW_AND_OLD_IMAGES`) so a consumer written against the emulator runs
+ * unchanged against real Streams in production (spec §4).
+ */
+/** Stream view type. Fixed to `NEW_AND_OLD_IMAGES` — incremental aggregation
+ * needs both images (spec §4). */
+type StreamViewType = 'NEW_AND_OLD_IMAGES';
+/** Stream event kind, matching DynamoDB Streams. */
+type ChangeEventName = 'INSERT' | 'MODIFY' | 'REMOVE';
+/**
+ * A single change event. Within one shard, `sequenceNumber` is monotonically
+ * increasing; across shards order is independent (spec §6).
+ */
+interface ChangeEvent<T = Record<string, unknown>> {
+    eventName: ChangeEventName;
+    table: string;
+    /** Resolved model name when known. */
+    model?: string;
+    keys: {
+        pk: string;
+        sk: string;
+    };
+    /** Present for MODIFY / REMOVE. */
+    oldImage?: T;
+    /** Present for INSERT / MODIFY. */
+    newImage?: T;
+    /** Deterministic-clock-derived creation time (ISO 8601). */
+    approximateCreationTime: string;
+    /** Monotonic within a shard (zero-padded for lexicographic ordering). */
+    sequenceNumber: string;
+    /** Partition = hash(pk). */
+    shardId: string;
+}
+/** A delivered batch. Records of the same shard are in `sequenceNumber` order. */
+interface ChangeBatch<T = Record<string, unknown>> {
+    records: ChangeEvent<T>[];
+}
+/**
+ * The consumer's response to a batch (spec §6, `ReportBatchItemFailures`
+ * equivalent). Returning the `sequenceNumber`s of records that failed lets the
+ * emulator advance the checkpoint past the successful prefix and redeliver only
+ * the failures.
+ */
+interface BatchResult {
+    /** `sequenceNumber`s of records the consumer failed to process. */
+    batchItemFailures?: string[];
+}
+/** The consumer handler. */
+type ChangeHandler = (batch: ChangeBatch) => Promise<BatchResult | void>;
+/** Unsubscribe handle. */
+type Unsubscribe = () => void;
+/** Where a fresh subscriber begins reading. */
+type StartingPosition = 'TRIM_HORIZON' | 'LATEST';
+/** Clock mode. `virtual` makes time deterministic via `advanceClock`. */
+type ClockMode = 'real' | 'virtual';
+/** Delivery mode (spec §7). */
+type CdcMode = 'inline' | 'queued' | 'record' | 'replay';
+/** Deterministic fault-injection spec (spec §8). All probabilities are seeded. */
+interface FaultSpec {
+    /** Probability [0,1] a delivered record is also re-delivered (duplicate). */
+    duplicate?: number;
+    /** Shuffle within-shard order on delivery (invariant-violation testing). */
+    reorder?: boolean;
+    /** Per-record virtual-time delivery delay range (ms). Requires queued mode. */
+    delay?: {
+        min: number;
+        max: number;
+    };
+    /** Probability [0,1] a record is dropped on first delivery then redelivered. */
+    dropThenRedeliver?: number;
+    /** Probability [0,1] a record is reported as a partial-batch failure. */
+    partialBatchFailure?: number;
+}
+/** A reference whose recompute should be forced to race a mark (spec §8, §7). */
+interface ConcurrentRecomputeRef {
+    /** Opaque node ref the harness recomputes concurrently with marking. */
+    ref: string;
+}
+/** A persisted event log (spec §10, record/replay). */
+interface EventLog {
+    seed: number;
+    events: ChangeEvent[];
+}
+/** Replay options (spec §10). */
+interface ReplayOptions {
+    /** Deliver events in a deterministic shuffled order (any-order replay). */
+    shuffle?: boolean;
+    /** Probability [0,1] each event is delivered twice during replay. */
+    duplicate?: number;
+}
+/** Constructor options (spec §11). */
+interface CdcEmulatorOptions {
+    /** Stream-enabled model classes (opt-in; default none). */
+    models?: Function[];
+    /** Delivery mode. Default `inline`. */
+    mode?: CdcMode;
+    /** Clock mode. Default `virtual` for queued, `real` otherwise. */
+    clock?: ClockMode;
+    /** Records per delivered batch. Default 100. */
+    batchSize?: number;
+    /** Max redelivery attempts before a record goes to the DLQ. Default 3. */
+    maxRetries?: number;
+    /** Where a subscriber starts. Default `TRIM_HORIZON`. */
+    startingPosition?: StartingPosition;
+    /** Seed for fault injection / shard assignment determinism. Default 1. */
+    seed?: number;
+    /** Number of shards events are partitioned across. Default 8. */
+    shardCount?: number;
+}
+type ShardId = string;
+
+/**
+ * `subscribe` — the declarative, batch CDC consumer builder (issue #153).
+ *
+ * The third sibling of `query` / `mutate` (GraphQL's query / mutation /
+ * **subscription**). Unlike them, `subscribe` DOES NOT subscribe and does not hit
+ * DynamoDB: it *returns* a {@link ChangeHandler} the consumer mounts on their own
+ * stream source (the CDC emulator locally, DynamoDB Streams → Lambda in
+ * production). Delivery — the actual subscription, the sink write, the dedup /
+ * idempotency store — lives OUTSIDE the boundary, in consumer code (see
+ * `docs/cdc-projection.md`). `DDBModel.subscribe` delegates here.
+ *
+ * The returned handler:
+ *
+ * - loops the batch and routes each event to its owning model by `event.model` /
+ *   `keys.pk` (via {@link parseChange});
+ * - typed-parses that event's `oldImage` / `newImage` into `[old, new]` and calls
+ *   the matching handler;
+ * - if a handler throws, records the event's `sequenceNumber` into
+ *   `batchItemFailures` (the Streams / Lambda `ReportBatchItemFailures` redelivery
+ *   protocol) and CONTINUES the batch — a single failing record never aborts the
+ *   whole batch. This mirrors how `mutate({ mode: 'parallel' })` aggregates per-op
+ *   ok/error; it is the delivery *protocol* shape, not delivery *semantics*, so it
+ *   stays inside the boundary;
+ * - NEVER writes a sink and NEVER dedups.
+ */
+
+/**
+ * One handler in the {@link SubscribeHandlers} map: given the parsed
+ * `[oldRecord, newRecord]` for an event routed to this model, project it (the body
+ * is CONSUMER code — a sink write, a diff, a log). May be async; a thrown error is
+ * caught by the batch loop and turned into a `batchItemFailures` entry. `old` / `new`
+ * are `T | null` (one side is null per event kind — INSERT / MODIFY / REMOVE).
+ */
+type SubscribeHandler<T> = (oldRecord: T | null, newRecord: T | null) => void | Promise<unknown>;
+/**
+ * The envelope-style handler map `subscribe` accepts, keyed by model name. Typed
+ * against the generated {@link import('../index.js').CdcModelRegistry} at the
+ * `DDBModel.subscribe` surface so keys are constrained to `@cdcProjected` models
+ * and each handler's `old` / `new` is inferred from the key. The runtime here is
+ * name-string driven (the type map is a compile-time-only concern).
+ */
+type SubscribeHandlers = Record<string, SubscribeHandler<never>>;
+/**
+ * Build the batch {@link ChangeHandler} from an envelope-style handler map. The
+ * runtime core behind `DDBModel.subscribe`.
+ */
+declare function buildSubscribeHandler(handlers: SubscribeHandlers): ChangeHandler;
+
+/**
+ * The generated **model name → model type** map (issue #153). graphddb ships it
+ * EMPTY; the codegen (`aaac generate`) emits a `declare module 'graphddb' { interface
+ * CdcModelRegistry { OrderModel: OrderModel; … } }` augmentation listing exactly the
+ * `@cdcProjected` models (see `docs/cdc-projection.md` §4). With the augmentation in
+ * scope, {@link DDBModel.subscribe}'s handler keys are constrained to the registry
+ * (typos / unknown or non-`@cdcProjected` model names are compile errors) and each
+ * handler's `old` / `new` are inferred from the key. Without it (no codegen run), the
+ * registry is empty and `subscribe` falls back to a permissive name→instance map.
+ */
+interface CdcModelRegistry {
+}
+/**
+ * The handler map `DDBModel.subscribe` accepts (issue #153). When the generated
+ * {@link CdcModelRegistry} is populated, keys are constrained to its model names and
+ * each handler's `(old, new)` is inferred from the mapped instance type. An empty
+ * registry (no codegen run) degrades to a permissive `Record` so authoring is not
+ * blocked before the augmentation is generated.
+ */
+type CdcSubscribeHandlers = keyof CdcModelRegistry extends never ? Record<string, SubscribeHandler<object>> : {
+    [K in keyof CdcModelRegistry]?: SubscribeHandler<CdcModelRegistry[K]>;
+};
 declare abstract class DDBModel {
     /** @internal Type brand — prevents primitives from structurally matching DDBModel. */
     private readonly __brand;
@@ -6071,6 +6254,45 @@ declare abstract class DDBModel {
     static mutate<const E extends WriteEnvelope>(envelope: E, options: {
         mode: 'parallel';
     }): Promise<MutateParallelResult<E>>;
+    /**
+     * Parse a single CDC {@link ChangeEvent} into the `[oldRecord, newRecord]` tuple
+     * for THIS model (issue #153 — the pure `(event) => [old, new]` typed mapper).
+     * It reuses the read path's `hydrate` on `oldImage` / `newImage` (ISO 8601 →
+     * `Date` for `@datetime`, embedded reconstruction) and returns typed instances of
+     * this model — **all fields**, no projection (narrowing does not reduce cost; the
+     * image is already on the stream).
+     *
+     * Routing + parse in one call: an event for a DIFFERENT model returns
+     * `[null, null]` (a valid event for this model always has ≥1 non-null side, so
+     * `[null, null]` is an unambiguous "not for this class" signal — no separate
+     * `owns()` guard). The present side per event kind mirrors DynamoDB Streams:
+     * INSERT → `[null, new]`, MODIFY → `[old, new]`, REMOVE → `[old, null]`.
+     *
+     * Only callable on a `@cdcProjected` model — the generated {@link CdcModelRegistry}
+     * types this at the `subscribe` surface, and at runtime a non-`@cdcProjected` model
+     * throws (loudly, never silently returning `[null, null]`, which would masquerade
+     * as a routing miss). Delivery / sink writes / dedup are the consumer's, outside
+     * this boundary (see `docs/cdc-projection.md`).
+     */
+    static fromChange<C extends abstract new (...args: never[]) => DDBModel>(this: C, event: ChangeEvent): [InstanceType<C> | null, InstanceType<C> | null];
+    /**
+     * Build a batch CDC {@link ChangeHandler} from an envelope-style handler map keyed
+     * by model name (issue #153 — the GraphQL query/mutation/**subscription** trio's
+     * third sibling). Unlike `query` / `mutate`, `subscribe` DOES NOT subscribe and
+     * does not hit DynamoDB: it *returns* a `(batch) => Promise<BatchResult>` the
+     * consumer mounts on their own stream source (the CDC emulator locally, DynamoDB
+     * Streams → Lambda in production) — delivery lives outside the boundary.
+     *
+     * The returned handler loops the batch, routes each event to its owning model by
+     * `event.model` / `keys.pk`, typed-parses via that model's `fromChange`, calls the
+     * matching handler, and — if a handler throws — records the event's
+     * `sequenceNumber` into `batchItemFailures` (the `ReportBatchItemFailures`
+     * redelivery protocol) and continues. It NEVER writes a sink and NEVER dedups
+     * (both are consumer concerns). Handler keys are constrained to the generated
+     * {@link CdcModelRegistry} (`@cdcProjected` models only); a key that is not a
+     * registered `@cdcProjected` model throws at build time.
+     */
+    static subscribe(handlers: CdcSubscribeHandlers): ChangeHandler;
     /**
      * Multi-key, multi-model batch read. Each {@link BatchGetRequest} contributes its
      * keys to a chunked `BatchGetItem` per physical table; results are re-grouped by
@@ -6559,6 +6781,19 @@ interface EntityMetadata {
      * Absent / empty for a plain entity.
      */
     maintainedFrom?: MaintainedFromMetadata[];
+    /**
+     * Whether the model is flagged **CDC-parseable** by `@cdcProjected()` (issue
+     * #153). It carries NO runtime side effect — it is purely a compile-/registration-
+     * time capability marker: `Model.fromChange(event)` (and, transitively,
+     * `DDBModel.subscribe` routing to this model) is gated on it, and it is the SSoT
+     * the codegen reads to emit the `CdcModelRegistry` module augmentation that types
+     * `subscribe`'s handlers by model name. `true` only on a model carrying the
+     * decorator; absent (⇒ falsy) for every plain entity, so a non-`@cdcProjected`
+     * model is byte-for-byte unchanged (backward compatible). Deliberately kept OFF
+     * the manifest / bridge (it is a host-runtime + TS-typing concern, like the
+     * maintenance signals — not a physical-schema fact like {@link ttlAttribute}).
+     */
+    cdcProjected?: boolean;
     /**
      * The physical attribute name of the model's `@ttl` field, when one is declared
      * (issue #172, Epic #167 — CFn generator C4). DynamoDB TTL requires a single
@@ -6574,117 +6809,4 @@ interface EntityMetadata {
     ttlAttribute?: string;
 }
 
-/**
- * CDC emulator types (issue #72). These types are **cdc-module-owned**; core
- * never references them. The {@link ChangeEvent} shape mirrors DynamoDB Streams
- * (`NEW_AND_OLD_IMAGES`) so a consumer written against the emulator runs
- * unchanged against real Streams in production (spec §4).
- */
-/** Stream view type. Fixed to `NEW_AND_OLD_IMAGES` — incremental aggregation
- * needs both images (spec §4). */
-type StreamViewType = 'NEW_AND_OLD_IMAGES';
-/** Stream event kind, matching DynamoDB Streams. */
-type ChangeEventName = 'INSERT' | 'MODIFY' | 'REMOVE';
-/**
- * A single change event. Within one shard, `sequenceNumber` is monotonically
- * increasing; across shards order is independent (spec §6).
- */
-interface ChangeEvent<T = Record<string, unknown>> {
-    eventName: ChangeEventName;
-    table: string;
-    /** Resolved model name when known. */
-    model?: string;
-    keys: {
-        pk: string;
-        sk: string;
-    };
-    /** Present for MODIFY / REMOVE. */
-    oldImage?: T;
-    /** Present for INSERT / MODIFY. */
-    newImage?: T;
-    /** Deterministic-clock-derived creation time (ISO 8601). */
-    approximateCreationTime: string;
-    /** Monotonic within a shard (zero-padded for lexicographic ordering). */
-    sequenceNumber: string;
-    /** Partition = hash(pk). */
-    shardId: string;
-}
-/** A delivered batch. Records of the same shard are in `sequenceNumber` order. */
-interface ChangeBatch<T = Record<string, unknown>> {
-    records: ChangeEvent<T>[];
-}
-/**
- * The consumer's response to a batch (spec §6, `ReportBatchItemFailures`
- * equivalent). Returning the `sequenceNumber`s of records that failed lets the
- * emulator advance the checkpoint past the successful prefix and redeliver only
- * the failures.
- */
-interface BatchResult {
-    /** `sequenceNumber`s of records the consumer failed to process. */
-    batchItemFailures?: string[];
-}
-/** The consumer handler. */
-type ChangeHandler = (batch: ChangeBatch) => Promise<BatchResult | void>;
-/** Unsubscribe handle. */
-type Unsubscribe = () => void;
-/** Where a fresh subscriber begins reading. */
-type StartingPosition = 'TRIM_HORIZON' | 'LATEST';
-/** Clock mode. `virtual` makes time deterministic via `advanceClock`. */
-type ClockMode = 'real' | 'virtual';
-/** Delivery mode (spec §7). */
-type CdcMode = 'inline' | 'queued' | 'record' | 'replay';
-/** Deterministic fault-injection spec (spec §8). All probabilities are seeded. */
-interface FaultSpec {
-    /** Probability [0,1] a delivered record is also re-delivered (duplicate). */
-    duplicate?: number;
-    /** Shuffle within-shard order on delivery (invariant-violation testing). */
-    reorder?: boolean;
-    /** Per-record virtual-time delivery delay range (ms). Requires queued mode. */
-    delay?: {
-        min: number;
-        max: number;
-    };
-    /** Probability [0,1] a record is dropped on first delivery then redelivered. */
-    dropThenRedeliver?: number;
-    /** Probability [0,1] a record is reported as a partial-batch failure. */
-    partialBatchFailure?: number;
-}
-/** A reference whose recompute should be forced to race a mark (spec §8, §7). */
-interface ConcurrentRecomputeRef {
-    /** Opaque node ref the harness recomputes concurrently with marking. */
-    ref: string;
-}
-/** A persisted event log (spec §10, record/replay). */
-interface EventLog {
-    seed: number;
-    events: ChangeEvent[];
-}
-/** Replay options (spec §10). */
-interface ReplayOptions {
-    /** Deliver events in a deterministic shuffled order (any-order replay). */
-    shuffle?: boolean;
-    /** Probability [0,1] each event is delivered twice during replay. */
-    duplicate?: number;
-}
-/** Constructor options (spec §11). */
-interface CdcEmulatorOptions {
-    /** Stream-enabled model classes (opt-in; default none). */
-    models?: Function[];
-    /** Delivery mode. Default `inline`. */
-    mode?: CdcMode;
-    /** Clock mode. Default `virtual` for queued, `real` otherwise. */
-    clock?: ClockMode;
-    /** Records per delivered batch. Default 100. */
-    batchSize?: number;
-    /** Max redelivery attempts before a record goes to the DLQ. Default 3. */
-    maxRetries?: number;
-    /** Where a subscriber starts. Default `TRIM_HORIZON`. */
-    startingPosition?: StartingPosition;
-    /** Seed for fault injection / shard assignment determinism. Default 1. */
-    seed?: number;
-    /** Number of shards events are partitioned across. Default 8. */
-    shardCount?: number;
-}
-type ShardId = string;
-
-export { type FaultSpec as $, type AggregateOptions as A, type BatchGetExecInput as B, type ChangeEvent as C, type DynamoDBOperation as D, type Executor as E, type FieldOptions as F, type GsiDefinition as G, type SelectBuilderSpec as H, type Item as I, type RawCondition as J, type KeyDefinition as K, type TransactionSpec as L, type ModelStatic as M, type Manifest as N, type RetryOverride as O, type PutInput as P, type ExecutionPlan as Q, type ReadExecOptions as R, type SelectableOf as S, type TransactWriteExecItem as T, type UpdateInput as U, type FieldMetadata as V, type WriteExecOptions as W, type ResolvedKey as X, type CdcEmulatorOptions as Y, type ChangeHandler as Z, type Unsubscribe as _, type ExecutorResult as a, type ContractCardinality as a$, type ConcurrentRecomputeRef as a0, type EventLog as a1, type ReplayOptions as a2, type ShardId as a3, type ViewDefinition as a4, type RelationMetadata as a5, type TransactionItemSpec as a6, type MaintainEffect as a7, type Param as a8, type ParamDescriptor as a9, BatchGetResult as aA, type BatchPutRequest as aB, type BatchResult as aC, type BatchWriteRequest as aD, CONTRACT_RANGE_FANOUT_CONCURRENCY as aE, type CdcMode as aF, type Change as aG, type ChangeBatch as aH, type ChangeEventName as aI, type ClockMode as aJ, type CollectionEffect as aK, type CollectionOptions as aL, type Column as aM, type ColumnMap as aN, type CommandContractMethodSpec as aO, type CommandInputShape as aP, type CommandMethod as aQ, type CommandPlan as aR, type CommandResolutionTarget as aS, type CommandResultKind as aT, type CommandSelectShape as aU, type CompiledFragment as aV, type ComposeSpec as aW, type CondSlot as aX, type ConditionCheckInput as aY, type Connection as aZ, type ContractCallSignature as a_, type DefinitionMap as aa, type OperationDefinition as ab, type WriteDefinitionOptions as ac, type PartialQueryKeyOf as ad, type StrictSelectSpec as ae, type ReadDefinitionOptions as af, type EntityInput as ag, type UniqueQueryKeyOf as ah, type EntityRef as ai, type ConditionInput as aj, type QueryModelContract as ak, type QueryMethodSpec as al, type CommandModelContract as am, type CommandMethodSpec as an, type ContractSpec as ao, type QuerySpec as ap, type CommandSpec as aq, type ContextSpec as ar, type OperationsDocument as as, type AnyOperationDefinition as at, type BridgeBundle as au, type ConditionSpec as av, type AggregateMetadata as aw, type BatchDeleteRequest as ax, type BatchGetOptions as ay, type BatchGetRequest as az, type WriteResult as b, type MutateMode as b$, type ContractCommandParams as b0, type ContractCommandResult as b1, type ContractComposeNode as b2, type ContractFromRef as b3, type ContractInputArity as b4, type ContractItem as b5, type ContractKeyFieldRef as b6, type ContractKeyInput as b7, type ContractKeyRef as b8, type ContractKeySpec as b9, type FragmentInput as bA, type GsiDefinitionMarker as bB, type GsiOptions as bC, type IdempotencyEffect as bD, type InProcessWriteDescriptor as bE, type InputArity as bF, type KeyDefinitionMarker as bG, type KeySegment as bH, type KeySlot as bI, type KeyStructure as bJ, type KeyedResult as bK, LIFECYCLE_CONTRACT_MARKER as bL, type LifecycleContract as bM, type LifecycleEffects as bN, type LiteralParam as bO, type MaintainItem as bP, type MaintainTrigger as bQ, type MaintenanceGraph as bR, type ManifestEntity as bS, type ManifestField as bT, type ManifestFieldType as bU, type ManifestGsi as bV, type ManifestKey as bW, type ManifestRelation as bX, type ManifestTable as bY, type MembershipEffect as bZ, type ModelRef as b_, type ContractKind as ba, type ContractMethodOp as bb, type ContractParamRef as bc, type ContractQueryParams as bd, type ContractResolution as be, type CounterAggregate as bf, type CounterEffect as bg, type CtxBase as bh, DEFAULT_MAX_ATTEMPTS as bi, DEFAULT_RETRY_POLICY as bj, type DeleteOptions as bk, type DeriveEffect as bl, type DerivedEdgeWrite as bm, type DerivedUpdate as bn, type DescriptorBinding as bo, ENTITY_WRITES_MARKER as bp, type EdgeEffect as bq, type EffectPath as br, type EmbeddedMetadata as bs, type EmitEffect as bt, type EntityWritesDefinition as bu, type EntityWritesShape as bv, type ExecutableCommandContract as bw, type ExecutableQueryContract as bx, type FilterInput as by, type FilterSpec as bz, type DeleteInput as c, type UpdateOptions as c$, type MutateOptions as c0, type MutateParallelResult as c1, type MutateTransactionResult as c2, type MutationBody as c3, type MutationDescriptorMap as c4, type MutationFragment as c5, type MutationInputProxy as c6, type MutationInputRef as c7, type MutationIntent as c8, type NumberParam as c9, type RelationBuilder as cA, type RelationConsistency as cB, type RelationLimitOptions as cC, type RelationPattern as cD, type RelationProjection as cE, type RelationReadOptions as cF, type RelationSelect as cG, type RelationSpec as cH, type RelationUpdateMode as cI, type RelationWriteOptions as cJ, type RequiresEffect as cK, type Resolution as cL, type RetryInfo as cM, type RetryOperationKind as cN, SPEC_VERSION as cO, type SegmentSpec as cP, type SegmentedKey as cQ, type SelectBuilder as cR, type SelectOf as cS, type SnapshotEffect as cT, type StartingPosition as cU, type StreamViewType as cV, type StringParam as cW, TransactionContext as cX, type TransactionItemType as cY, type UniqueEffect as cZ, type Updatable as c_, type OperationKind as ca, type OperationSpec as cb, type ParallelOpResult as cc, type ParamKind as cd, type ParamSpec as ce, type ParamStructure as cf, type PersistCtx as cg, type PersistOrigin as ch, type PlannedCommandMethod as ci, type ProjectionMap as cj, type ProjectionTransformOp as ck, type PutOptions as cl, type QueryContractMethodSpec as cm, type QueryEnvelopeResult as cn, type QueryKeyOf as co, type QueryMethod as cp, type QueryResult as cq, type RangeConditionSpec as cr, type ReadEnvelope as cs, type ReadOpCtx as ct, type ReadOpKind as cu, type ReadOperationType as cv, type ReadRouteDescriptor as cw, type ReadRouteOptions as cx, type ReadRouteResult as cy, type RecordedCompose as cz, type BatchWriteExecItem as d, mintContractKeyFieldRef as d$, type ViewSourceSlice as d0, type WhenSpec as d1, type WriteCtx as d2, type WriteDescriptor as d3, type WriteEnvelope as d4, type WriteInput as d5, type WriteKind as d6, type WriteLifecyclePhase as d7, type WriteMiddleware as d8, type WriteOperationType as d9, from as dA, getEntityWrites as dB, gsi as dC, identity as dD, isColumn as dE, isCommandModelContract as dF, isCommandPlan as dG, isContractComposeNode as dH, isContractFromRef as dI, isContractKeyFieldRef as dJ, isContractKeyRef as dK, isContractParamRef as dL, isEntityWritesDefinition as dM, isKeySegment as dN, isLifecycleContract as dO, isMaintainTrigger as dP, isMutationFragment as dQ, isMutationInputRef as dR, isParam as dS, isPlannedCommandMethod as dT, isQueryModelContract as dU, isRetryableError as dV, isRetryableTransactionCancellation as dW, k as dX, key as dY, lifecyclePhaseForIntent as dZ, maintainTrigger as d_, type WriteRecorder as da, type WriteResultProjection as db, attachModelClass as dc, buildDeleteInput as dd, buildMaintenanceGraph as de, buildPutInput as df, buildUpdateInput as dg, collectViewDefinitions as dh, compileFragment as di, compileMutationPlan as dj, compileSingleFragmentPlan as dk, cond as dl, contractOfMethodSpec as dm, definePlan as dn, entityWrites as dp, executeBatchGet as dq, executeBatchWrite as dr, executeCommandMethod as ds, executeDelete as dt, executeKeyedBatchGet as du, executePut as dv, executeQueryMethod as dw, executeRangeFanout as dx, executeTransaction as dy, executeUpdate as dz, type BatchExecOptions as e, mintContractParamRef as e0, mutation as e1, param as e2, preview as e3, publicCommandModel as e4, publicQueryModel as e5, query as e6, resolveLifecycle as e7, wholeKeysSentinel as e8, DDBModel as f, type PrimaryKeyOf as g, type RequestContext as h, type Middleware as i, type ReadRequestKind as j, type CtxModel as k, type ReadParams as l, type ReadRequestCtx as m, type RetryPolicy as n, type ExecutionPlanSpec as o, type EntityMetadata as p, type ModelKind as q, type DynamoType as r, type ProjectionTransform as s, type MaintainEvent as t, type MembershipPredicate as u, type MaintainConsistency as v, type MaintainUpdateMode as w, type MembershipPredicateOp as x, type RelationOptions as y, type AggregateValue as z };
+export { type FaultSpec as $, type AggregateOptions as A, type BatchGetExecInput as B, type ChangeEvent as C, type DynamoDBOperation as D, type Executor as E, type FieldOptions as F, type GsiDefinition as G, type SelectBuilderSpec as H, type Item as I, type RawCondition as J, type KeyDefinition as K, type TransactionSpec as L, type ModelStatic as M, type Manifest as N, type RetryOverride as O, type PutInput as P, type ExecutionPlan as Q, type ReadExecOptions as R, type SelectableOf as S, type TransactWriteExecItem as T, type UpdateInput as U, type FieldMetadata as V, type WriteExecOptions as W, type ResolvedKey as X, type CdcEmulatorOptions as Y, type ChangeHandler as Z, type Unsubscribe as _, type ExecutorResult as a, type Connection as a$, type ConcurrentRecomputeRef as a0, type EventLog as a1, type ReplayOptions as a2, type ShardId as a3, type ViewDefinition as a4, type RelationMetadata as a5, type TransactionItemSpec as a6, type MaintainEffect as a7, type Param as a8, type ParamDescriptor as a9, BatchGetResult as aA, type BatchPutRequest as aB, type BatchResult as aC, type BatchWriteRequest as aD, CONTRACT_RANGE_FANOUT_CONCURRENCY as aE, type CdcMode as aF, type CdcModelRegistry as aG, type CdcSubscribeHandlers as aH, type Change as aI, type ChangeBatch as aJ, type ChangeEventName as aK, type ClockMode as aL, type CollectionEffect as aM, type CollectionOptions as aN, type Column as aO, type ColumnMap as aP, type CommandContractMethodSpec as aQ, type CommandInputShape as aR, type CommandMethod as aS, type CommandPlan as aT, type CommandResolutionTarget as aU, type CommandResultKind as aV, type CommandSelectShape as aW, type CompiledFragment as aX, type ComposeSpec as aY, type CondSlot as aZ, type ConditionCheckInput as a_, type DefinitionMap as aa, type OperationDefinition as ab, type WriteDefinitionOptions as ac, type PartialQueryKeyOf as ad, type StrictSelectSpec as ae, type ReadDefinitionOptions as af, type EntityInput as ag, type UniqueQueryKeyOf as ah, type EntityRef as ai, type ConditionInput as aj, type QueryModelContract as ak, type QueryMethodSpec as al, type CommandModelContract as am, type CommandMethodSpec as an, type ContractSpec as ao, type QuerySpec as ap, type CommandSpec as aq, type ContextSpec as ar, type OperationsDocument as as, type AnyOperationDefinition as at, type BridgeBundle as au, type ConditionSpec as av, type AggregateMetadata as aw, type BatchDeleteRequest as ax, type BatchGetOptions as ay, type BatchGetRequest as az, type WriteResult as b, type MembershipEffect as b$, type ContractCallSignature as b0, type ContractCardinality as b1, type ContractCommandParams as b2, type ContractCommandResult as b3, type ContractComposeNode as b4, type ContractFromRef as b5, type ContractInputArity as b6, type ContractItem as b7, type ContractKeyFieldRef as b8, type ContractKeyInput as b9, type FilterInput as bA, type FilterSpec as bB, type FragmentInput as bC, type GsiDefinitionMarker as bD, type GsiOptions as bE, type IdempotencyEffect as bF, type InProcessWriteDescriptor as bG, type InputArity as bH, type KeyDefinitionMarker as bI, type KeySegment as bJ, type KeySlot as bK, type KeyStructure as bL, type KeyedResult as bM, LIFECYCLE_CONTRACT_MARKER as bN, type LifecycleContract as bO, type LifecycleEffects as bP, type LiteralParam as bQ, type MaintainItem as bR, type MaintainTrigger as bS, type MaintenanceGraph as bT, type ManifestEntity as bU, type ManifestField as bV, type ManifestFieldType as bW, type ManifestGsi as bX, type ManifestKey as bY, type ManifestRelation as bZ, type ManifestTable as b_, type ContractKeyRef as ba, type ContractKeySpec as bb, type ContractKind as bc, type ContractMethodOp as bd, type ContractParamRef as be, type ContractQueryParams as bf, type ContractResolution as bg, type CounterAggregate as bh, type CounterEffect as bi, type CtxBase as bj, DEFAULT_MAX_ATTEMPTS as bk, DEFAULT_RETRY_POLICY as bl, type DeleteOptions as bm, type DeriveEffect as bn, type DerivedEdgeWrite as bo, type DerivedUpdate as bp, type DescriptorBinding as bq, ENTITY_WRITES_MARKER as br, type EdgeEffect as bs, type EffectPath as bt, type EmbeddedMetadata as bu, type EmitEffect as bv, type EntityWritesDefinition as bw, type EntityWritesShape as bx, type ExecutableCommandContract as by, type ExecutableQueryContract as bz, type DeleteInput as c, TransactionContext as c$, type ModelRef as c0, type MutateMode as c1, type MutateOptions as c2, type MutateParallelResult as c3, type MutateTransactionResult as c4, type MutationBody as c5, type MutationDescriptorMap as c6, type MutationFragment as c7, type MutationInputProxy as c8, type MutationInputRef as c9, type ReadRouteResult as cA, type RecordedCompose as cB, type RelationBuilder as cC, type RelationConsistency as cD, type RelationLimitOptions as cE, type RelationPattern as cF, type RelationProjection as cG, type RelationReadOptions as cH, type RelationSelect as cI, type RelationSpec as cJ, type RelationUpdateMode as cK, type RelationWriteOptions as cL, type RequiresEffect as cM, type Resolution as cN, type RetryInfo as cO, type RetryOperationKind as cP, SPEC_VERSION as cQ, type SegmentSpec as cR, type SegmentedKey as cS, type SelectBuilder as cT, type SelectOf as cU, type SnapshotEffect as cV, type StartingPosition as cW, type StreamViewType as cX, type StringParam as cY, type SubscribeHandler as cZ, type SubscribeHandlers as c_, type MutationIntent as ca, type NumberParam as cb, type OperationKind as cc, type OperationSpec as cd, type ParallelOpResult as ce, type ParamKind as cf, type ParamSpec as cg, type ParamStructure as ch, type PersistCtx as ci, type PersistOrigin as cj, type PlannedCommandMethod as ck, type ProjectionMap as cl, type ProjectionTransformOp as cm, type PutOptions as cn, type QueryContractMethodSpec as co, type QueryEnvelopeResult as cp, type QueryKeyOf as cq, type QueryMethod as cr, type QueryResult as cs, type RangeConditionSpec as ct, type ReadEnvelope as cu, type ReadOpCtx as cv, type ReadOpKind as cw, type ReadOperationType as cx, type ReadRouteDescriptor as cy, type ReadRouteOptions as cz, type BatchWriteExecItem as d, isRetryableTransactionCancellation as d$, type TransactionItemType as d0, type UniqueEffect as d1, type Updatable as d2, type UpdateOptions as d3, type ViewSourceSlice as d4, type WhenSpec as d5, type WriteCtx as d6, type WriteDescriptor as d7, type WriteEnvelope as d8, type WriteInput as d9, executePut as dA, executeQueryMethod as dB, executeRangeFanout as dC, executeTransaction as dD, executeUpdate as dE, from as dF, getEntityWrites as dG, gsi as dH, identity as dI, isColumn as dJ, isCommandModelContract as dK, isCommandPlan as dL, isContractComposeNode as dM, isContractFromRef as dN, isContractKeyFieldRef as dO, isContractKeyRef as dP, isContractParamRef as dQ, isEntityWritesDefinition as dR, isKeySegment as dS, isLifecycleContract as dT, isMaintainTrigger as dU, isMutationFragment as dV, isMutationInputRef as dW, isParam as dX, isPlannedCommandMethod as dY, isQueryModelContract as dZ, isRetryableError as d_, type WriteKind as da, type WriteLifecyclePhase as db, type WriteMiddleware as dc, type WriteOperationType as dd, type WriteRecorder as de, type WriteResultProjection as df, attachModelClass as dg, buildDeleteInput as dh, buildMaintenanceGraph as di, buildPutInput as dj, buildSubscribeHandler as dk, buildUpdateInput as dl, collectViewDefinitions as dm, compileFragment as dn, compileMutationPlan as dp, compileSingleFragmentPlan as dq, cond as dr, contractOfMethodSpec as ds, definePlan as dt, entityWrites as du, executeBatchGet as dv, executeBatchWrite as dw, executeCommandMethod as dx, executeDelete as dy, executeKeyedBatchGet as dz, type BatchExecOptions as e, k as e0, key as e1, lifecyclePhaseForIntent as e2, maintainTrigger as e3, mintContractKeyFieldRef as e4, mintContractParamRef as e5, mutation as e6, param as e7, preview as e8, publicCommandModel as e9, publicQueryModel as ea, query as eb, resolveLifecycle as ec, wholeKeysSentinel as ed, DDBModel as f, type PrimaryKeyOf as g, type RequestContext as h, type Middleware as i, type ReadRequestKind as j, type CtxModel as k, type ReadParams as l, type ReadRequestCtx as m, type RetryPolicy as n, type ExecutionPlanSpec as o, type EntityMetadata as p, type ModelKind as q, type DynamoType as r, type ProjectionTransform as s, type MaintainEvent as t, type MembershipPredicate as u, type MaintainConsistency as v, type MaintainUpdateMode as w, type MembershipPredicateOp as x, type RelationOptions as y, type AggregateValue as z };

package/docs/cdc-projection.md

@@ -0,0 +1,167 @@
+# GraphDDB — CDC Projection (typed-consumer-IF)
+
+CDC projection lets you turn a model's change stream into **typed records** you can
+push to an **external sink** — BigQuery, OpenSearch, S3, Neptune — for analytics or
+search, decoupled from the table. Delivery is asynchronous over CDC (DynamoDB Streams)
+and must tolerate at-least-once semantics (a redelivered event must not double-write).
+
+graphddb's job here is narrow and deliberate: **parse a change event into a typed
+record**. It does *not* subscribe to the stream, write to the sink, or de-duplicate —
+those belong to your infrastructure. This keeps the library out of your delivery
+semantics (upsert, idempotency, dedup) while still giving you fully typed access to
+what changed.
+
+## The boundary
+
+graphddb owns the **parse → typed record** contract, and nothing downstream of it.
+
+| graphddb (the contract) | you (the runtime) |
+| --- | --- |
+| Enable CDC parse on a source model (`@cdcProjected`) | Subscribe to the CDC stream (emulator / DynamoDB Streams) |
+| Parse `oldImage` / `newImage` into typed instances | Write to the sink (upsert / delete) |
+| Route an event to its owning model | Idempotency store (dedup / at-least-once) |
+| Produce the `(event) => [old, new]` typed mapper | Actual delivery and retry decisions |
+
+What graphddb hands you is a pure function (and a batch handler built on it) — never a
+subscription, a sink write, or a dedup store.
+
+## API
+
+### 1. `@cdcProjected()` — mark a source model
+
+Enables CDC parse on the model. `fromChange` and `subscribe` typing only apply to a
+`@cdcProjected` model (calling `fromChange` on an un-annotated model is an error). The
+decorator has no runtime effect — it only marks the model as CDC-parseable.
+
+```ts
+import { model, cdcProjected, DDBModel, string, number, datetime, key, k } from 'graphddb';
+
+@model({ table: 'Orders', prefix: 'ORDER' })
+@cdcProjected()
+class OrderModel extends DDBModel {
+  static readonly keys = key<{ orderId: string }>((c) => ({
+    pk: k`ORDER#${c.orderId}`, sk: k`META`,
+  }));
+
+  @string orderId!: string;
+  @string status!: string;
+  @number amountTotal!: number;
+  @datetime updatedAt!: Date;
+}
+```
+
+### 2. `Model.fromChange(event)` — procedural, single event
+
+Takes a `ChangeEvent` and returns the `[oldRecord, newRecord]` tuple, parsing
+`oldImage` / `newImage` into typed model instances (the same hydration used for reads —
+ISO strings become `Date`, embedded objects are reconstructed). It returns **all
+fields** (there is no field projection — see [Design notes](#design-notes)).
+
+```ts
+const [oldRecord, newRecord] = OrderModel.fromChange(event);
+//     ^ OrderModel | null    ^ OrderModel | null
+
+// One side is null depending on the event kind:
+//   INSERT → [null,      newRecord]
+//   MODIFY → [oldRecord, newRecord]
+//   REMOVE → [oldRecord, null     ]
+//   (event for a different model) → [null, null]   ← self-routing
+
+if (oldRecord || newRecord) {
+  if (!newRecord) {
+    // REMOVE — delete; derive the sink key from oldRecord
+  } else {
+    // INSERT | MODIFY — upsert; diff against oldRecord if you need change detection
+  }
+}
+```
+
+A valid event for this model always has at least one non-null side, so `[null, null]`
+is an unambiguous "this event is not for this model" signal. You don't need a separate
+guard — `fromChange` does routing **and** parse in one call.
+
+### 3. `DDBModel.subscribe(handlers)` — declarative, batch
+
+The third sibling of `query` / `mutate` (GraphQL's query / mutation / **subscription**).
+It takes a handler map keyed by model name. Unlike `query` / `mutate`, which hit
+DynamoDB, **`subscribe` does not subscribe**: it *returns* a `ChangeHandler`
+(`(batch) => Promise<BatchResult>`) that you mount on your own stream source.
+
+```ts
+// graphddb side: build a batch handler that parses + routes + dispatches (no sink, no dedup)
+const handler = DDBModel.subscribe({
+  OrderModel: (old, neu) => {        // old, neu: OrderModel | null (typed via the generated registry)
+    if (!neu) return opensearch.delete({ id: old!.orderId });
+    return opensearch.index({ id: neu.orderId, body: { status: neu.status } });
+  },
+  UserModel: (old, neu) => { /* old, neu: UserModel | null */ },
+});
+
+// your side: the real subscription lives here (delivery is yours)
+emulator.subscribe(handler);              // local (CDC emulator)
+// export const lambdaHandler = handler;   // production (DynamoDB Streams → Lambda)
+```
+
+The returned handler:
+
+- loops the batch and routes each event to its owning model;
+- typed-parses via that model's `fromChange`, then calls the matching handler;
+- if a handler throws, records that record's `sequenceNumber` into `batchItemFailures`
+  (the Streams / Lambda partial-batch-failure protocol, so only the failed records are
+  redelivered);
+- **never writes a sink and never dedups** — the `opensearch.*` calls above are your code.
+
+Recording `batchItemFailures` is the delivery *protocol* shape (which records to
+redeliver), not delivery *semantics* (upsert / dedup), so it stays inside the boundary.
+
+### 4. `CdcModelRegistry` — generated type registry
+
+The `subscribe` handlers are keyed by model name (a string), so type inference needs a
+type-level "model name → type" map. graphddb's code generation emits it for you as a
+module augmentation:
+
+```ts
+// generated by `graphddb generate` (you do not write this)
+declare module 'graphddb' {
+  interface CdcModelRegistry {
+    OrderModel: OrderModel;
+    UserModel: UserModel;
+  }
+}
+```
+
+With it in your build, `subscribe`'s keys are constrained to your registered models
+(typos and unknown model names are compile errors) and each handler's `old` / `neu` is
+inferred from the key.
+
+## The GraphQL trio
+
+| GraphQL | DDBModel | Executed by | Returns |
+| --- | --- | --- | --- |
+| query | `DDBModel.query(envelope)` | graphddb (hits DynamoDB) | result object |
+| mutation | `DDBModel.mutate(envelope)` | graphddb (hits DynamoDB) | result object |
+| subscription | `DDBModel.subscribe(handlers)` | **you** (mount it) | `ChangeHandler` |
+
+Only subscription is "executed by you, returns a handler rather than a result" —
+because CDC delivery lives outside the boundary.
+
+## Design notes
+
+- **No field projection (`fromChange` returns all fields).** Narrowing the fields does
+  not reduce network cost (the image is already on the stream), so there is no `select`.
+  Shape the record however you like in plain TS inside your handler.
+- **`[null, null]` for routing.** A valid event always has a non-null side, so both
+  being null is an unambiguous "not for this model" signal — `fromChange` handles
+  routing and parse without an extra guard.
+- **`subscribe` returns a handler.** So that graphddb owns neither the subscription nor
+  delivery. The return type being a `ChangeHandler` (not a result) is the visible
+  expression of the boundary.
+- **Naming.** `subscribe` completes the GraphQL query / mutation / subscription trio
+  (distinct from `emulator.subscribe(handler)`, which is the actual subscription).
+
+## See also
+
+- [`spec.md` §7 — Relations & maintained access paths](./spec.md#7-relations)
+- [`design-patterns.md` §10 — External Projection](./design-patterns.md#10-external-projection)
+- [`cdc-emulator.md`](./cdc-emulator.md) — the CDC emulator that drives stream handlers locally
+- [`class-hydration.md`](./class-hydration.md) — how raw items become typed instances

package/docs/design-patterns.md

@@ -47,7 +47,7 @@ graph, the stream drain, and the rebuild planner consume every pattern uniformly
 | 7 | [Aggregate Counter](#7-aggregate-counter) | `@aggregate(..., { pattern: 'counter', value: count() })` | ✅ Phase 1 (`count()`) / stream (`max()`) |
 | 8 | [Versioned / Latest Pointer](#8-versioned--latest-pointer) | `@hasOne(... versionedLatest)` + `@hasMany(... versionedHistory)` | ✅ Phase 3 |
 | 9 | [Reverse Lookup](#9-reverse-lookup) | GSI (both directions) or `dualEdge` two-row sync | ✅ Phase 1 (GSI) / Phase 3 (`dualEdge`) |
-| 10 | [External Projection](#10-external-projection) | typed-consumer-IF contract (redesign — see #153) | 🚧 redesign |
+| 10 | [External Projection](#10-external-projection) | typed-consumer-IF contract (`@cdcProjected` + `fromChange` / `subscribe`) | ✅ |
 
 ---
 
@@ -494,23 +494,28 @@ OpenSearch, S3, Neptune — for analytics or search, decoupled from the table. T
 projection is asynchronous and must tolerate at-least-once delivery (a redelivered
 event must not double-write).
 
-**(b) How it is being redesigned (🚧 #153).** The previous `defineProjection` builder +
+**(b) How to declare it in graphddb.** The previous `defineProjection` builder +
 `ProjectionSinkDrain` / `InMemoryProjectionSink` runtime baked the sink-delivery
 semantics (upsert, idempotency, dedup) into the library — a boundary overreach: the
 actual sink write happens inside the consumer's CDC infrastructure, outside graphddb.
-That runtime was **removed in 0.4.0** (issue #152). The redesign (issue #153) reframes
-external projection as a **typed-consumer-IF contract**: from a declared source +
-projection fields + idempotency-key extraction, graphddb emits a typed
-`(changeImage) => TypedProjectionRecord` mapper for the consumer to call inside its own
-sink delivery — graphddb owns the *parse → typed record* contract, not the delivery.
-External projection is neither a Model nor a relation, so it does not ride a decorator.
+That runtime was **removed in 0.4.0** (issue #152). External projection is now a
+**typed-consumer-IF contract** (issue #153): mark the source model with
+`@cdcProjected()`, then parse a CDC change event into typed instances — `Model.fromChange(event)`
+returns `[oldRecord, newRecord]`, and `DDBModel.subscribe(handlers)` (the GraphQL-style
+sibling of `query` / `mutate`) returns a `ChangeHandler` the consumer mounts on its own
+stream. graphddb owns the *parse → typed record* contract; subscription, sink delivery,
+and idempotency stay with the consumer. See [`cdc-projection.md`](./cdc-projection.md)
+for the full design.
 
 **(c) Read & write behavior.** Out of scope for this library (the data is read from the
-sink; delivery + idempotency live in the consumer's CDC code). See #153 for the
-typed-consumer-IF contract design.
-
-**(d) Constraints & phase status.** 🚧 Redesign (#153). The sink runtime is gone in
-0.4.0; the typed-consumer-IF replacement lands separately.
+sink; delivery + idempotency live in the consumer's CDC code). graphddb only parses the
+change event into a typed record; see [`cdc-projection.md`](./cdc-projection.md) for the
+typed-consumer-IF contract.
+
+**(d) Constraints & phase status.** ✅ Shipped (issue #153). The sink runtime was removed
+in 0.4.0; the typed-consumer-IF replacement (`@cdcProjected` + `fromChange` + `subscribe`
++ the generated `CdcModelRegistry`) is implemented and tested (unit + emulator-driven
+integration).
 
 ---
 

package/docs/spec.md

@@ -546,9 +546,10 @@ Shared vocabulary (confirmed across the epic):
   view model** — `materializedView` / `sparseView` — are declared with `@model({ kind })`
   + `@maintainedFrom` (§7.1 below). The **versioned** presets ride the `@hasOne` /
   `@hasMany` `pattern` discriminated union (`versionedLatest` / `versionedHistory`).
-  External projection is being redesigned as a typed-consumer-IF contract (#153) and
-  has no decorator. Unknown values on a relation are accepted by the open-ended union
-  but not lowered.
+  External projection is a typed-consumer-IF contract (#153); it is not a relation
+  `pattern` — the source model is marked with `@cdcProjected()` instead (see
+  [`cdc-projection.md`](./cdc-projection.md)). Unknown values on a relation are
+  accepted by the open-ended union but not lowered.
 - **`write.maintainedOn`** — cross-entity triggers `"<Entity>.<event>"`. The
   Entity segment is the **logical** entity name (`PostModel → 'Post'`; or the
   `@model({ prefix })` value sans `#`), and the event is one of
@@ -634,7 +635,11 @@ The latest/history key binding is derived from each target model's own `key` fie
 composed snapshot×2 IR. (A self-co-located form is a deferred follow-up.)
 
 External projection's old `defineProjection` / `ProjectionSinkDrain` runtime was
-**removed in 0.4.0** and is being redesigned as a typed-consumer-IF contract (#153).
+**removed in 0.4.0** and is now a typed-consumer-IF contract (#153):
+the source model is marked `@cdcProjected()`, `Model.fromChange(event)` parses a CDC
+change event into `[oldRecord, newRecord]`, and `DDBModel.subscribe(handlers)` returns a
+`ChangeHandler` the consumer mounts on its own stream (subscription / sink delivery /
+idempotency stay with the consumer). See [`cdc-projection.md`](./cdc-projection.md).
 
 ### 7.2 Stream maintenance — outbox → CDC drain (`updateMode: 'stream'`, #130)