graphddb 0.7.10 → 0.8.1

package/README.md

@@ -74,13 +74,13 @@ const User = UserModel.asModel();
 
 // Connect the client once. GraphDDB owns throttle / transient retries, so set
 // `maxAttempts: 1` to avoid double retries (SDK × library) — see "Retry & throttling" below.
-DDBModel.setClient(new DynamoDBClient({ maxAttempts: 1 }));
+graphddb.config.client(new DynamoDBClient({ maxAttempts: 1 }));
 
 // READ —— only the fields you select appear in the result type.
 const user = await User.query({ userId: 'alice' }, { name: true });
 
 // WRITE —— a unified envelope that writes multiple items atomically (default mode: 'transaction').
-await DDBModel.mutate({
+await graphddb.mutate({
   user: { update: User, key: { userId: 'alice' }, input: { name: 'Alice B.' } },
 });
 
@@ -89,7 +89,7 @@ await User.putItem({ userId: 'alice', name: 'Alice' });
 ```
 
 Reads center on `query` (a single PK / unique GSI lookup) / `list` (multiple items, with a cursor).
-Writes center on `DDBModel.mutate` (a unified envelope), while `putItem` / `updateItem` / `deleteItem` are
+Writes center on `graphddb.mutate` (a unified envelope), while `putItem` / `updateItem` / `deleteItem` are
 positioned secondarily as raw base operations named after the DynamoDB API. For the full API and options,
 see [`docs/spec.md`](./docs/spec.md).
 
@@ -196,7 +196,7 @@ Each capability is summarized here only. For details, operator lists, and proced
 - **Filtering** —— a declarative, type-safe server-side `filter` (compatible with `FilterExpression` /
   AppSync `ModelFilterInput`). `Model.col` + the `cond` raw escape hatch are shared by read filters / write
   `condition`s. For the operator list, see [`docs/spec.md`](./docs/spec.md).
-- **Middleware / Hooks** —— `DDBModel.use` for host-side hooks on reads / writes (logging, metrics, tenant /
+- **Middleware / Hooks** —— `graphddb.config.use` for host-side hooks on reads / writes (logging, metrics, tenant /
   authorization scoping). Host-only and non-serialized. For hook points, see [`docs/middleware.md`](./docs/middleware.md).
 - **Class hydration** —— `options.hydrate` loads read results into host-language domain objects (opt-in,
   Phase 1: `query` top level). [`docs/class-hydration.md`](./docs/class-hydration.md).
@@ -209,7 +209,7 @@ Each capability is summarized here only. For details, operator lists, and proced
   aggregation. [`docs/cdc-emulator.md`](./docs/cdc-emulator.md).
 - **CDC projection** —— a typed-consumer-IF that parses the CDC change events of a `@cdcProjected()`
   source model into typed records. `Model.fromChange(event)` returns `[old, new]`, and
-  `DDBModel.subscribe(handlers)` (the sibling of `query` / `mutate`) produces a `ChangeHandler` the
+  `graphddb.subscribe(handlers)` (the sibling of `query` / `mutate`) produces a `ChangeHandler` the
   consumer mounts on its own stream. graphddb owns parse→typed record only; subscription, sink
   delivery, and idempotency are the consumer's. [`docs/cdc-projection.md`](./docs/cdc-projection.md).
 - **CloudFormation generation** —— `graphddb generate cloudformation` emits a CloudFormation template for
@@ -231,7 +231,7 @@ documentation available offline at hand. On GitHub, follow the links in the tabl
 |----------|-------------|
 | [Specification](./docs/spec.md) | Core API: entities, structured keys/GSIs, query/filter, relations, batch/transaction, design rules, runtime behavior. |
 | [Design patterns](./docs/design-patterns.md) | Mapping representative DynamoDB design patterns onto graphddb features (how to declare `pattern` / `@model({ kind })` + `@maintainedFrom` / `@aggregate`, read & write maintenance, per-phase coverage). |
-| [Middleware / Hooks](./docs/middleware.md) | The `DDBModel.use` host-side middleware: hook points read R1–R5 / write W1–W5, `{ context }`, ordering. |
+| [Middleware / Hooks](./docs/middleware.md) | The `graphddb.config.use` host-side middleware: hook points read R1–R5 / write W1–W5, `{ context }`, ordering. |
 | [CQRS contract layer](./docs/cqrs-contract.md) | Public Query/Command contracts, cardinality matrix, N+1 safety, composition across contracts, context boundaries. |
 | [Mutation → command derivation](./docs/mutation-command-derivation.md) | The internal write-plan composition DSL behind the Command IF (`entityWrites`, fragment composition, derivation of atomic `TransactWriteItems`). |
 | [Class hydration](./docs/class-hydration.md) | Opt-in `options.hydrate` that loads read results into host objects (Phase 1: `query` top level). |

package/dist/cdc/index.d.ts

@@ -1,7 +1,351 @@
-export { C as CdcEmulator, M as MAINT_OUTBOX_PK_PREFIX, a as MaintenanceDrain, b as MaintenanceDrainOptions, c as createCdcEmulator, d as createMaintenanceDrain, e as createMaintenanceDrainHandler, p as parseChange } from '../from-change-Ty95KA8C.js';
-export { B as BatchResult, C as CdcEmulatorOptions, a as CdcMode, b as ChangeBatch, c as ChangeEvent, d as ChangeEventName, e as ChangeHandler, f as ClockMode, g as ConcurrentRecomputeRef, E as EventLog, F as FaultSpec, R as ReplayOptions, S as ShardId, h as StartingPosition, i as StreamViewType, j as SubscribeHandler, k as SubscribeHandlers, U as Unsubscribe, l as buildSubscribeHandler } from '../maintenance-view-adapter-BAZ9uBGe.js';
-import '@aws-sdk/client-dynamodb';
-import '../types-BQLzTEqh.js';
+import { w as CdcEmulatorOptions, x as ChangeHandler, y as Unsubscribe, F as FaultSpec, z as ConcurrentRecomputeRef, v as ChangeEvent, A as EventLog, G as ReplayOptions, H as ShardId, I as MaintainTrigger, E as EffectPath, g as ProjectionMap, j as MembershipPredicate } from '../key-DZtjAQDh.js';
+export { J as BatchResult, K as CdcMode, L as ChangeBatch, N as ChangeEventName, O as ClockMode, V as StartingPosition, X as StreamViewType, Y as SubscribeHandler, Z as SubscribeHandlers, _ as buildSubscribeHandler } from '../key-DZtjAQDh.js';
+import { E as EntityMetadata } from '../types-DW__-Icc.js';
+import '../types-2PMXEn5x.js';
+
+/**
+ * CDC emulator (issue #72). Subscribes to the core write-capture seam
+ * ({@link ChangeCaptureRegistry}) and turns each {@link RawWriteRecord} into a
+ * DynamoDB-Streams-equivalent {@link ChangeEvent}, then delivers events to a
+ * consumer under a deterministic delivery contract (spec §6): per-shard ordered,
+ * batched, at-least-once, with checkpoint/resume, partial-batch failure, and a
+ * dead-letter queue. Faults (duplicate / reorder / delay / dropThenRedeliver /
+ * partialBatchFailure) and a concurrent-recompute race are injectable and
+ * seeded for deterministic reproduction (spec §8).
+ *
+ * The emulator is dev/test only. The {@link ChangeEvent} type and delivery
+ * contract match real Streams so a consumer is portable to production (spec §1).
+ */
+
+/**
+ * The CDC emulator (spec §10 API). Construct via {@link createCdcEmulator}.
+ */
+declare class CdcEmulator {
+    private readonly mode;
+    private readonly clockMode;
+    private readonly batchSize;
+    private readonly maxRetries;
+    private readonly startingPosition;
+    private readonly shardCount;
+    private readonly seed;
+    private rng;
+    private faultSpec;
+    private concurrentRecompute;
+    private concurrentRecomputeHook;
+    /** Per-shard monotonic sequence counter. */
+    private seqCounters;
+    /** Per-shard delivery queue (queued/replay modes). */
+    private queues;
+    /** Per-shard last successfully checkpointed sequence number. */
+    private checkpointMap;
+    /**
+     * Per-shard set of acked sequence numbers (as ints) not yet folded into the
+     * checkpoint. The checkpoint advances over the contiguous prefix of acked
+     * sequences (ReportBatchItemFailures semantics): a sequence is checkpointed
+     * only once every sequence at or before it has been acked.
+     */
+    private ackedSeqs;
+    /** Per-shard count of sequences ever assigned, to bound the prefix scan. */
+    private maxSeqSeen;
+    /** Recorded event log (record mode and always, for replay()). */
+    private log;
+    /** Dead-letter buffer. */
+    private dlq;
+    private handler;
+    /** Virtual clock (ms since EPOCH). */
+    private clockMs;
+    /** Pending async work from inline-mode captures, awaited by callers. */
+    private inflight;
+    private detachCapture;
+    private readonly models;
+    constructor(opts?: CdcEmulatorOptions);
+    private onRawWrite;
+    private toChangeEvent;
+    /** Parse a zero-padded sequence string back to its integer value. */
+    private seqToInt;
+    /** Render an integer sequence as the zero-padded string form. */
+    private intToSeq;
+    /**
+     * Advance a shard's checkpoint over the contiguous prefix of acked sequence
+     * numbers. Starting just past the current checkpoint, consume every
+     * consecutive acked sequence; stop at the first gap (an un-acked sequence
+     * still pending redelivery). Consumed sequences are removed from the acked
+     * set to bound its size.
+     */
+    private advanceCheckpoint;
+    private deriveEventName;
+    private nowIso;
+    private enqueue;
+    /**
+     * Deliver buffered, due records to the consumer, advancing per-shard
+     * checkpoints on success and redelivering failures. In `queued`/`replay`
+     * modes call this (or {@link advanceClock}) to drive delivery; `inline` calls
+     * it automatically after each capture.
+     */
+    pump(maxBatches?: number): Promise<void>;
+    /**
+     * Pull up to `batchSize` due records from a shard, preserving ascending
+     * sequence order (spec §6). When the `reorder` fault is on, the within-shard
+     * order is deliberately shuffled to exercise invariant detection.
+     */
+    private collectBatch;
+    private deliverBatch;
+    /** Register the consumer. Returns an unsubscribe handle. */
+    subscribe(handler: ChangeHandler): Unsubscribe;
+    /** Await any inline-mode async deliveries triggered by writes. */
+    flush(): Promise<void>;
+    /**
+     * Advance the virtual clock by `ms` and deliver records whose due-time has
+     * arrived (spec §7). Reproduces throttle T / sweep period / staleness S time
+     * behavior deterministically (AC4).
+     */
+    advanceClock(ms: number): Promise<void>;
+    /** Current virtual time (ms since the emulator epoch). */
+    now(): number;
+    /** Configure fault injection (spec §8). Merges into the current spec. */
+    fault(spec: FaultSpec): void;
+    /**
+     * Force a recompute to race a mark for the given ref (spec §8, §7). The
+     * harness supplies the actual recompute via {@link onConcurrentRecompute};
+     * this records which ref to race and arms the hook.
+     */
+    injectConcurrentRecompute(ref: ConcurrentRecomputeRef): void;
+    /**
+     * Register the callback the emulator invokes (before each record reaches the
+     * consumer) when a concurrent recompute has been injected. This is how the
+     * test harness wires its recompute into the delivery race.
+     */
+    onConcurrentRecompute(hook: (ref: ConcurrentRecomputeRef, event: ChangeEvent) => void | Promise<void>): void;
+    /** Snapshot the recorded event log (spec §10). */
+    record(): EventLog;
+    /**
+     * Replay an event log through the delivery pipeline, optionally shuffled and
+     * duplicated (spec §10, AC5). Used to prove **replay equivalence**: starting
+     * from any global order plus duplicates, a consumer that respects the
+     * per-shard ordering contract (spec §6) reaches a final aggregate equal to a
+     * full recompute from source.
+     *
+     * The shuffle models cross-shard reordering and at-least-once chaos at the
+     * delivery boundary. It must NOT, however, break the within-shard ordering
+     * guarantee that real DynamoDB Streams provides and that incremental
+     * aggregation depends on — so after shuffling/duplicating, each shard's queue
+     * is re-sorted into ascending original `sequenceNumber` order before delivery.
+     * The original `sequenceNumber` (assigned at record time) is preserved so it
+     * remains the source-of-truth ordering the consumer can rely on.
+     */
+    replay(log: EventLog, opts?: ReplayOptions): Promise<void>;
+    /** Per-shard checkpoints (last acked sequence number). */
+    checkpoints(): Record<ShardId, string>;
+    /** Dead-lettered events (exceeded maxRetries). */
+    deadLetters(): ChangeEvent[];
+    /** Reset delivery state and re-seed (keeps the subscription + model opt-in). */
+    reset(): void;
+    /** Tear down: detach from the core seam and disable model streaming. */
+    close(): void;
+}
+/** Create a CDC emulator (spec §10). */
+declare function createCdcEmulator(opts?: CdcEmulatorOptions): CdcEmulator;
+
+/**
+ * Decorator-metadata → maintenance-graph `ViewDefinition` adapter (issue #152).
+ *
+ * ## What this replaces
+ *
+ * The old `defineView` / `defineVersioned` builders (deleted) registered
+ * `ViewDefinition`s into a side `ViewRegistry`, which the maintenance graph read.
+ * That builder carried a registration side-effect + a `generation` counter (a
+ * silent-drop guard). This adapter removes that whole path: it derives the SAME
+ * `ViewDefinition` IR purely from the declarative `MetadataRegistry` — the
+ * Contract-layer SSoT, whose own `generation` counter is the single
+ * invalidation source — so a view declared via `@model({ kind })` + `@maintainedFrom`
+ * (and a versioned relation declared via `@hasOne/@hasMany` `pattern`) is discovered
+ * with no separate registry.
+ *
+ * ## IR invariance
+ *
+ * The `ViewDefinition` / `ViewSourceSlice` shapes are UNCHANGED. The maintenance
+ * graph, the K (#130) stream/drain, and the L (#131) rebuild consume the adapter's
+ * output exactly as they consumed `ViewRegistry.getAll()`. Only the SOURCE of the
+ * definitions moved from a builder side-effect to declarative metadata.
+ *
+ * ## Order independence (issue #152 hardening)
+ *
+ * Stacked `@maintainedFrom` declarations carry no order meaning. The adapter rejects
+ * — symmetrically, so the error is identical whichever order the decorators are
+ * stacked — any two declarations on the same view that:
+ *   1. write the SAME projection target attribute (ambiguous duplicate projection);
+ *   2. maintain the SAME `collection.field`;
+ *   3. bind the SAME view-key field to a DIFFERENT source path (the view-row identity
+ *      would be inconsistent across sources).
+ * A legitimate multi-source view (different sources filling DIFFERENT fields, all
+ * binding the SAME key the SAME way) is fine.
+ */
+
+type AnyModelClass = abstract new (...args: any[]) => any;
+/** The view source slice IR the maintenance graph consumes (one per source × view). */
+interface ViewSourceSlice {
+    readonly sourceClass: AnyModelClass;
+    readonly maintainedOn: readonly MaintainTrigger[];
+    readonly keys: Readonly<Record<string, EffectPath>>;
+    readonly project: ProjectionMap;
+    readonly collection?: {
+        readonly field: string;
+        readonly maxItems?: number;
+        readonly orderBy?: EffectPath;
+        readonly orderDir?: 'ASC' | 'DESC';
+    };
+    readonly predicate?: MembershipPredicate;
+}
+/** The view definition IR — an independent view row maintained from one or more sources. */
+interface ViewDefinition {
+    readonly name: string;
+    readonly viewClass: AnyModelClass;
+    readonly pattern: 'materializedView' | 'sparseView';
+    readonly slices: readonly ViewSourceSlice[];
+    readonly updateMode?: 'mutation' | 'stream';
+    readonly consistency?: 'transactional' | 'eventual';
+}
+
+/**
+ * CDC **maintenance drain** (issue #130) — the asynchronous lower for
+ * `updateMode: 'stream'` maintainers (Epic #118 §5.1).
+ *
+ * A synchronous (`updateMode: 'mutation'`) maintainer composes its owner-row write
+ * into the SAME atomic `TransactWriteItems` as the source write (#127). A
+ * `updateMode: 'stream'` maintainer instead emits a **maintenance-outbox** marker row
+ * (`OUTBOX#MAINT#…`) ATOMICALLY with the source write (the #130 compile lowering in
+ * `src/spec/mutation-command.ts`), and THIS consumer — driven by the {@link
+ * import('./emulator.js').CdcEmulator} (or, in production, real DynamoDB Streams +
+ * a Lambda built around {@link createMaintenanceDrainHandler}) — applies the owner-row
+ * write asynchronously.
+ *
+ * ## Why a separate async path exists (not just "do it later synchronously")
+ *
+ * The async path realizes the maintenance operations a single synchronous
+ * `UpdateExpression` cannot express against an unread item:
+ *
+ * - **collection `maxItems` trim** — keeping a bounded, ordered list requires reading
+ *   the current list, appending, sorting, and trimming (a read-modify-write); a
+ *   synchronous `list_append` can only append (Phase 1 was append-only, #127).
+ * - **`removed`-driven splice** — removing an entry from a maintained collection on a
+ *   source `removed` event likewise needs the current list.
+ * - **running `max(field)`** — a conditional `SET` (`#a = :v` guarded by
+ *   `attribute_not_exists(#a) OR #a < :v`) whose failed guard, if run synchronously,
+ *   would roll back the legitimate source write.
+ *
+ * ## Delivery guarantees (reused from the CDC substrate)
+ *
+ * The maintenance-outbox row is recorded ATOMICALLY with the source write, so the
+ * intent can never be lost ("wrote the row, lost the maintenance" is impossible). The
+ * CDC substrate then delivers it **at-least-once**, **per-shard ordered** (a shard is
+ * `hash(pk)`, and the outbox row's `pk` is keyed off the SOURCE row's key, so all
+ * maintenance events for one source entity land on one shard in source-write order),
+ * with a **DLQ** for poison events. This consumer is therefore written to be
+ * **idempotent / commutative** wherever at-least-once redelivery could double-apply:
+ *
+ * - a `snapshot` `SET` is naturally idempotent (re-applying the same projection is a
+ *   no-op);
+ * - a `collection` rebuild de-duplicates by the projected item's identity key, so a
+ *   redelivered append does not grow the list twice;
+ * - a `max` conditional `SET` is idempotent (the guard rejects a non-greater value);
+ * - a `count` `ADD` is the ONE non-idempotent op — but the source-row create guard
+ *   (`attribute_not_exists`) means a given source `created` event is emitted at most
+ *   once into the outbox, and the per-shard checkpoint advances only over acked events,
+ *   so a `count` is applied once per genuine source lifecycle. (A duplicate DELIVERY of
+ *   the same event is folded by the consumer's per-event de-dup set within a drain.)
+ */
+
+/**
+ * The PK prefix a maintenance-outbox row keys on — the single source of truth shared
+ * with the compiler ({@link import('../spec/mutation-command.js')}'s
+ * `MAINT_OUTBOX_PK_PREFIX`). The drain selects its events by `keys.pk.startsWith` of
+ * this. Kept as a local literal (rather than importing a non-exported compiler const)
+ * so the cdc module does not depend on the spec module; the value is asserted equal by
+ * the integration tests that round-trip a real stream maintainer through both.
+ */
+declare const MAINT_OUTBOX_PK_PREFIX = "OUTBOX#MAINT#";
+/** Options for {@link createMaintenanceDrain}. */
+interface MaintenanceDrainOptions {
+    /**
+     * The model classes (or `ModelStatic`s) whose stream maintainers this drain
+     * applies. The drain builds a scoped {@link MaintenanceGraph} over them to resolve
+     * each maintenance-outbox event back to its declared effect. Defaults to the GLOBAL
+     * registry when omitted.
+     */
+    readonly models?: readonly Function[];
+    /**
+     * The {@link ViewDefinition}s (`defineView`) whose maintainers this drain applies
+     * (issue #132). A view's destination is its dedicated view model; its source
+     * classes should also be in {@link models} so the drain can resolve their
+     * maintenance-outbox events. Defaults to none.
+     */
+    readonly views?: readonly ViewDefinition[];
+}
+/**
+ * A maintenance drain: a CDC consumer ({@link ChangeHandler}) that applies the
+ * owner-row writes for `updateMode: 'stream'` maintainers. Construct via
+ * {@link createMaintenanceDrain}, then `subscribe` its {@link handler} to a
+ * {@link import('./emulator.js').CdcEmulator} (dev/test) or wire it into a real
+ * Streams Lambda (production).
+ */
+declare class MaintenanceDrain {
+    private readonly graph;
+    /** Owner entity name → its model class (for the owner-row key derivation). */
+    private readonly ownerByName;
+    /** Per-event-id de-dup within a single handler invocation (at-least-once). */
+    private appliedSeq;
+    /** Count of owner-row writes applied (test/diagnostic). */
+    private applied;
+    constructor(opts?: MaintenanceDrainOptions);
+    /** The CDC {@link ChangeHandler} to subscribe to an emulator / Streams source. */
+    readonly handler: ChangeHandler;
+    /** Resolve one maintenance-outbox event to its effect and apply the owner-row write. */
+    private applyOne;
+    /** Resolve a maintenance-outbox event back to the declared {@link MaintainItem}. */
+    private resolve;
+    /** A `snapshot` SET of each projected attribute onto the owner row (idempotent). */
+    private applySnapshot;
+    /**
+     * A sparse-view **membership** write (#133): evaluate the membership predicate against
+     * the source image; PUT the view row (its projection + key fields) when the predicate
+     * holds, DELETE it when it flips false. A source `removed` event always deletes (the
+     * source no longer exists, so its view row must disappear regardless of the predicate).
+     *
+     * Both ops are idempotent under at-least-once redelivery: a repeated PUT writes the same
+     * row, a repeated DELETE is a no-op. The view row is keyed by the source identity
+     * (`effect.keys`), so the PUT/DELETE always targets the SAME physical row the predicate
+     * gates.
+     */
+    private applyMembership;
+    /**
+     * A running `max`: read the owner row, and `SET` the attribute to the source value
+     * only when it is greater (or absent). Implemented as a conditional update so a
+     * redelivered / out-of-order older value never regresses the stored max — idempotent
+     * and commutative under at-least-once delivery.
+     */
+    private applyMax;
+    /**
+     * A bounded `collection`: read the current list, apply the event (append for a
+     * `created`/`updated` source, splice for a `removed`), de-duplicate by the projected
+     * identity key, order by `orderBy` (in `orderDir`, default DESC), trim to `maxItems`, and write the whole
+     * list back. The read-modify-write is exactly what a single synchronous
+     * `UpdateExpression` cannot do — the reason a bounded/ordered collection is a stream
+     * maintainer (Phase 1 sync was append-only).
+     */
+    private applyCollection;
+    /** Owner-row writes applied so far (test/diagnostic). */
+    appliedCount(): number;
+    /** Clear the per-delivery de-dup set + counters (test reset). */
+    reset(): void;
+}
+/** Create a {@link MaintenanceDrain} (issue #130). */
+declare function createMaintenanceDrain(opts?: MaintenanceDrainOptions): MaintenanceDrain;
+/**
+ * Create just the CDC {@link ChangeHandler} for a maintenance drain — the form to
+ * subscribe to an emulator or wire into a production Streams Lambda. A thin wrapper
+ * over {@link createMaintenanceDrain} for callers that only need the handler.
+ */
+declare function createMaintenanceDrainHandler(opts?: MaintenanceDrainOptions): ChangeHandler;
 
 /**
  * Deterministic primitives for the CDC emulator (issue #72). All fault
@@ -35,4 +379,44 @@ declare function hashString(value: string): number;
 /** Compute the shard id for a partition key over `shardCount` shards. */
 declare function shardIdFor(pk: string, shardCount: number): string;
 
-export { SeededRandom, hashString, shardIdFor };
+/**
+ * `fromChange` — the pure `(event) => [old, new]` typed mapper (issue #153).
+ *
+ * This is graphddb's HALF of the CDC-projection boundary (see
+ * `docs/cdc-projection.md`): it parses a raw {@link ChangeEvent}'s `oldImage` /
+ * `newImage` into typed model instances and does nothing downstream of that (no
+ * sink write, no dedup, no subscription). `Model.fromChange(event)` on `DDBModel`
+ * delegates here.
+ *
+ * The two responsibilities packed into one call are **routing** and **parse**:
+ *
+ * - Routing — an event that is not for `modelClass` yields `[null, null]`. A valid
+ *   event for the class always has at least one non-null image, so `[null, null]`
+ *   is an unambiguous "not for this model" signal and no separate `owns()` guard is
+ *   needed. The match is by `event.model` (the resolved model name the write path /
+ *   emulator stamps) when present, falling back to the model's PK prefix
+ *   (`keys.pk` begins with `<prefix>`) when the event carries no `model`.
+ * - Parse — each present image is hydrated via the existing {@link hydrate}
+ *   (raw item → typed value, INCLUDING ISO 8601 → `Date` for `@datetime` and
+ *   embedded reconstruction), returning ALL fields (no projection — narrowing does
+ *   not reduce network cost since the image is already on the stream). The hydrated
+ *   plain record is then loaded onto a fresh model instance so the result is a
+ *   genuine `InstanceType` (like the read path's `{ hydrate }` factory option).
+ *
+ * The image side present per event kind mirrors DynamoDB Streams:
+ *
+ * - INSERT → `[null,      new ]`
+ * - MODIFY → `[old,       new ]`
+ * - REMOVE → `[old,       null]`
+ */
+
+/**
+ * Parse a {@link ChangeEvent} into the `[oldRecord, newRecord]` tuple for the given
+ * model. Returns `[null, null]` when the event is not for this model (routing). The
+ * caller (`DDBModel.fromChange`) supplies the resolved metadata + class; this
+ * function is the runtime core and is deliberately model-name-string driven so
+ * `DDBModel.subscribe` can reuse it when routing a batch.
+ */
+declare function parseChange<T extends object>(event: ChangeEvent, metadata: EntityMetadata, modelName: string, modelClass: new () => T): [T | null, T | null];
+
+export { CdcEmulator, CdcEmulatorOptions, ChangeEvent, ChangeHandler, ConcurrentRecomputeRef, EventLog, FaultSpec, MAINT_OUTBOX_PK_PREFIX, MaintenanceDrain, type MaintenanceDrainOptions, ReplayOptions, SeededRandom, ShardId, Unsubscribe, createCdcEmulator, createMaintenanceDrain, createMaintenanceDrainHandler, hashString, parseChange, shardIdFor };

package/dist/cdc/index.js

@@ -8,13 +8,13 @@ import {
   createMaintenanceDrainHandler,
   hashString,
   shardIdFor
-} from "../chunk-AD6ZQTTE.js";
+} from "../chunk-GS4C5VGO.js";
 import {
   buildSubscribeHandler,
   parseChange
-} from "../chunk-DFUKGU2Q.js";
-import "../chunk-3ZU2VW3L.js";
-import "../chunk-PDUVTYC5.js";
+} from "../chunk-HNY2EJPV.js";
+import "../chunk-L2NEDS7U.js";
+import "../chunk-XTWXMOHD.js";
 export {
   CdcEmulator,
   MAINT_OUTBOX_PK_PREFIX,

package/dist/{chunk-AD6ZQTTE.js → chunk-GS4C5VGO.js}

@@ -1,6 +1,6 @@
 import {
   buildMaintenanceGraph
-} from "./chunk-DFUKGU2Q.js";
+} from "./chunk-HNY2EJPV.js";
 import {
   ChangeCaptureRegistry,
   ClientManager,
@@ -9,7 +9,7 @@ import {
   buildDeleteInput,
   buildPutInput,
   resolveModelClass
-} from "./chunk-3ZU2VW3L.js";
+} from "./chunk-L2NEDS7U.js";
 
 // src/cdc/prng.ts
 var SeededRandom = class {
@@ -800,10 +800,6 @@ export {
   shardIdFor,
   CdcEmulator,
   createCdcEmulator,
-  pathField,
-  projectFrom,
-  compareDesc,
-  orderAndTrimCollection,
   MAINT_OUTBOX_PK_PREFIX,
   MaintenanceDrain,
   createMaintenanceDrain,