graphddb 0.4.3 → 0.5.1

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { S as SelectableOf, g as PrimaryKeyOf, h as RequestContext, i as Middleware, j as ReadRequestKind, k as CtxModel, l as ReadParams, m as ReadRequestCtx, D as DynamoDBOperation, I as Item, E as Executor, n as RetryPolicy, o as ExecutionPlanSpec, p as EntityMetadata, K as KeyDefinition, G as GsiDefinition, q as ModelKind, F as FieldOptions, r as DynamoType, s as ProjectionTransform, t as MaintainEvent, u as MembershipPredicate, v as MaintainConsistency, w as MaintainUpdateMode, x as MembershipPredicateOp, y as RelationOptions, A as AggregateOptions, z as AggregateValue, H as SelectBuilderSpec, J as RawCondition, L as TransactionSpec, N as Manifest, O as RetryOverride, Q as ExecutionPlan, V as FieldMetadata, X as ResolvedKey, R as ReadExecOptions, a as ExecutorResult, B as BatchGetExecInput, P as PutInput, W as WriteExecOptions, b as WriteResult, U as UpdateInput, c as DeleteInput, d as BatchWriteExecItem, e as BatchExecOptions, T as TransactWriteExecItem, Y as CdcEmulatorOptions, Z as ChangeHandler, _ as Unsubscribe, $ as FaultSpec, a0 as ConcurrentRecomputeRef, C as ChangeEvent, a1 as EventLog, a2 as ReplayOptions, a3 as ShardId, a4 as ViewDefinition, a5 as RelationMetadata, a6 as TransactionItemSpec, a7 as MaintainEffect, M as ModelStatic, f as DDBModel, a8 as Param, a9 as ParamDescriptor, aa as DefinitionMap, ab as OperationDefinition, ac as WriteDefinitionOptions, ad as PartialQueryKeyOf, ae as StrictSelectSpec, af as ReadDefinitionOptions, ag as EntityInput, ah as UniqueQueryKeyOf, ai as EntityRef, aj as ConditionInput, ak as QueryModelContract, al as QueryMethodSpec, am as CommandModelContract, an as CommandMethodSpec, ao as ContractSpec, ap as QuerySpec, aq as CommandSpec, ar as ContextSpec, as as OperationsDocument, at as AnyOperationDefinition, au as BridgeBundle, av as ConditionSpec } from './types-BWOrWcbd.js';
-export { aw as AggregateMetadata, ax as BatchDeleteRequest, ay as BatchGetOptions, az as BatchGetRequest, aA as BatchGetResult, aB as BatchPutRequest, aC as BatchResult, aD as BatchWriteRequest, aE as CONTRACT_RANGE_FANOUT_CONCURRENCY, aF as CdcMode, aG as Change, aH as ChangeBatch, aI as ChangeEventName, aJ as ClockMode, aK as CollectionEffect, aL as CollectionOptions, aM as Column, aN as ColumnMap, aO as CommandContractMethodSpec, aP as CommandInputShape, aQ as CommandMethod, aR as CommandPlan, aS as CommandResolutionTarget, aT as CommandResultKind, aU as CommandSelectShape, aV as CompiledFragment, aW as ComposeSpec, aX as CondSlot, aY as ConditionCheckInput, aZ as Connection, a_ as ContractCallSignature, a$ as ContractCardinality, b0 as ContractCommandParams, b1 as ContractCommandResult, b2 as ContractComposeNode, b3 as ContractFromRef, b4 as ContractInputArity, b5 as ContractItem, b6 as ContractKeyFieldRef, b7 as ContractKeyInput, b8 as ContractKeyRef, b9 as ContractKeySpec, ba as ContractKind, bb as ContractMethodOp, bc as ContractParamRef, bd as ContractQueryParams, be as ContractResolution, bf as CounterAggregate, bg as CounterEffect, bh as CtxBase, bi as DEFAULT_MAX_ATTEMPTS, bj as DEFAULT_RETRY_POLICY, bk as DeleteOptions, bl as DeriveEffect, bm as DerivedEdgeWrite, bn as DerivedUpdate, bo as DescriptorBinding, bp as ENTITY_WRITES_MARKER, bq as EdgeEffect, br as EffectPath, bs as EmbeddedMetadata, bt as EmitEffect, bu as EntityWritesDefinition, bv as EntityWritesShape, bw as ExecutableCommandContract, bx as ExecutableQueryContract, by as FilterInput, bz as FilterSpec, bA as FragmentInput, bB as GsiDefinitionMarker, bC as GsiOptions, bD as IdempotencyEffect, bE as InProcessWriteDescriptor, bF as InputArity, bG as KeyDefinitionMarker, bH as KeySegment, bI as KeySlot, bJ as KeyStructure, bK as KeyedResult, bL as LIFECYCLE_CONTRACT_MARKER, bM as LifecycleContract, bN as LifecycleEffects, bO as LiteralParam, bP as MaintainItem, bQ as MaintainTrigger, bR as MaintenanceGraph, bS as ManifestEntity, bT as ManifestField, bU as ManifestFieldType, bV as ManifestGsi, bW as ManifestKey, bX as ManifestRelation, bY as ManifestTable, bZ as MembershipEffect, b_ as ModelRef, b$ as MutateMode, c0 as MutateOptions, c1 as MutateParallelResult, c2 as MutateTransactionResult, c3 as MutationBody, c4 as MutationDescriptorMap, c5 as MutationFragment, c6 as MutationInputProxy, c7 as MutationInputRef, c8 as MutationIntent, c9 as NumberParam, ca as OperationKind, cb as OperationSpec, cc as ParallelOpResult, cd as ParamKind, ce as ParamSpec, cf as ParamStructure, cg as PersistCtx, ch as PersistOrigin, ci as PlannedCommandMethod, cj as ProjectionMap, ck as ProjectionTransformOp, cl as PutOptions, cm as QueryContractMethodSpec, cn as QueryEnvelopeResult, co as QueryKeyOf, cp as QueryMethod, cq as QueryResult, cr as RangeConditionSpec, cs as ReadEnvelope, ct as ReadOpCtx, cu as ReadOpKind, cv as ReadOperationType, cw as ReadRouteDescriptor, cx as ReadRouteOptions, cy as ReadRouteResult, cz as RecordedCompose, cA as RelationBuilder, cB as RelationConsistency, cC as RelationLimitOptions, cD as RelationPattern, cE as RelationProjection, cF as RelationReadOptions, cG as RelationSelect, cH as RelationSpec, cI as RelationUpdateMode, cJ as RelationWriteOptions, cK as RequiresEffect, cL as Resolution, cM as RetryInfo, cN as RetryOperationKind, cO as SPEC_VERSION, cP as SegmentSpec, cQ as SegmentedKey, cR as SelectBuilder, cS as SelectOf, cT as SnapshotEffect, cU as StartingPosition, cV as StreamViewType, cW as StringParam, cX as TransactionContext, cY as TransactionItemType, cZ as UniqueEffect, c_ as Updatable, c$ as UpdateOptions, d0 as ViewSourceSlice, d1 as WhenSpec, d2 as WriteCtx, d3 as WriteDescriptor, d4 as WriteEnvelope, d5 as WriteInput, d6 as WriteKind, d7 as WriteLifecyclePhase, d8 as WriteMiddleware, d9 as WriteOperationType, da as WriteRecorder, db as WriteResultProjection, dc as attachModelClass, dd as buildDeleteInput, de as buildMaintenanceGraph, df as buildPutInput, dg as buildUpdateInput, dh as collectViewDefinitions, di as compileFragment, dj as compileMutationPlan, dk as compileSingleFragmentPlan, dl as cond, dm as contractOfMethodSpec, dn as definePlan, dp as entityWrites, dq as executeBatchGet, dr as executeBatchWrite, ds as executeCommandMethod, dt as executeDelete, du as executeKeyedBatchGet, dv as executePut, dw as executeQueryMethod, dx as executeRangeFanout, dy as executeTransaction, dz as executeUpdate, dA as from, dB as getEntityWrites, dC as gsi, dD as identity, dE as isColumn, dF as isCommandModelContract, dG as isCommandPlan, dH as isContractComposeNode, dI as isContractFromRef, dJ as isContractKeyFieldRef, dK as isContractKeyRef, dL as isContractParamRef, dM as isEntityWritesDefinition, dN as isKeySegment, dO as isLifecycleContract, dP as isMaintainTrigger, dQ as isMutationFragment, dR as isMutationInputRef, dS as isParam, dT as isPlannedCommandMethod, dU as isQueryModelContract, dV as isRetryableError, dW as isRetryableTransactionCancellation, dX as k, dY as key, dZ as lifecyclePhaseForIntent, d_ as maintainTrigger, d$ as mintContractKeyFieldRef, e0 as mintContractParamRef, e1 as mutation, e2 as param, e3 as preview, e4 as publicCommandModel, e5 as publicQueryModel, e6 as query, e7 as resolveLifecycle, e8 as wholeKeysSentinel } from './types-BWOrWcbd.js';
+import { S as SelectableOf, g as PrimaryKeyOf, h as RequestContext, i as Middleware, j as ReadRequestKind, k as CtxModel, l as ReadParams, m as ReadRequestCtx, D as DynamoDBOperation, I as Item, E as Executor, n as RetryPolicy, o as ExecutionPlanSpec, p as EntityMetadata, K as KeyDefinition, G as GsiDefinition, q as ModelKind, F as FieldOptions, r as DynamoType, s as ProjectionTransform, t as MaintainEvent, u as MembershipPredicate, v as MaintainConsistency, w as MaintainUpdateMode, x as MembershipPredicateOp, y as RelationOptions, A as AggregateOptions, z as AggregateValue, H as SelectBuilderSpec, J as RawCondition, L as TransactionSpec, N as Manifest, O as RetryOverride, Q as ExecutionPlan, V as FieldMetadata, X as ResolvedKey, R as ReadExecOptions, a as ExecutorResult, B as BatchGetExecInput, P as PutInput, W as WriteExecOptions, b as WriteResult, U as UpdateInput, c as DeleteInput, d as BatchWriteExecItem, e as BatchExecOptions, T as TransactWriteExecItem, Y as CdcEmulatorOptions, Z as ChangeHandler, _ as Unsubscribe, $ as FaultSpec, a0 as ConcurrentRecomputeRef, C as ChangeEvent, a1 as EventLog, a2 as ReplayOptions, a3 as ShardId, a4 as ViewDefinition, a5 as RelationMetadata, a6 as TransactionItemSpec, a7 as MaintainEffect, M as ModelStatic, f as DDBModel, a8 as Param, a9 as ParamDescriptor, aa as DefinitionMap, ab as OperationDefinition, ac as WriteDefinitionOptions, ad as PartialQueryKeyOf, ae as StrictSelectSpec, af as ReadDefinitionOptions, ag as EntityInput, ah as UniqueQueryKeyOf, ai as EntityRef, aj as ConditionInput, ak as QueryModelContract, al as QueryMethodSpec, am as CommandModelContract, an as CommandMethodSpec, ao as ContractSpec, ap as QuerySpec, aq as CommandSpec, ar as ContextSpec, as as OperationsDocument, at as AnyOperationDefinition, au as BridgeBundle, av as ConditionSpec } from './types-B9rJ1z3H.js';
+export { aw as AggregateMetadata, ax as BatchDeleteRequest, ay as BatchGetOptions, az as BatchGetRequest, aA as BatchGetResult, aB as BatchPutRequest, aC as BatchResult, aD as BatchWriteRequest, aE as CONTRACT_RANGE_FANOUT_CONCURRENCY, aF as CdcMode, aG as CdcModelRegistry, aH as CdcSubscribeHandlers, aI as Change, aJ as ChangeBatch, aK as ChangeEventName, aL as ClockMode, aM as CollectionEffect, aN as CollectionOptions, aO as Column, aP as ColumnMap, aQ as CommandContractMethodSpec, aR as CommandInputShape, aS as CommandMethod, aT as CommandPlan, aU as CommandResolutionTarget, aV as CommandResultKind, aW as CommandSelectShape, aX as CompiledFragment, aY as ComposeSpec, aZ as CondSlot, a_ as ConditionCheckInput, a$ as Connection, b0 as ContractCallSignature, b1 as ContractCardinality, b2 as ContractCommandParams, b3 as ContractCommandResult, b4 as ContractComposeNode, b5 as ContractFromRef, b6 as ContractInputArity, b7 as ContractItem, b8 as ContractKeyFieldRef, b9 as ContractKeyInput, ba as ContractKeyRef, bb as ContractKeySpec, bc as ContractKind, bd as ContractMethodOp, be as ContractParamRef, bf as ContractQueryParams, bg as ContractResolution, bh as CounterAggregate, bi as CounterEffect, bj as CtxBase, bk as DEFAULT_MAX_ATTEMPTS, bl as DEFAULT_RETRY_POLICY, bm as DeleteOptions, bn as DeriveEffect, bo as DerivedEdgeWrite, bp as DerivedUpdate, bq as DescriptorBinding, br as ENTITY_WRITES_MARKER, bs as EdgeEffect, bt as EffectPath, bu as EmbeddedMetadata, bv as EmitEffect, bw as EntityWritesDefinition, bx as EntityWritesShape, by as ExecutableCommandContract, bz as ExecutableQueryContract, bA as FilterInput, bB as FilterSpec, bC as FragmentInput, bD as GsiDefinitionMarker, bE as GsiOptions, bF as IdempotencyEffect, bG as InProcessWriteDescriptor, bH as InputArity, bI as KeyDefinitionMarker, bJ as KeySegment, bK as KeySlot, bL as KeyStructure, bM as KeyedResult, bN as LIFECYCLE_CONTRACT_MARKER, bO as LifecycleContract, bP as LifecycleEffects, bQ as LiteralParam, bR as MaintainItem, bS as MaintainTrigger, bT as MaintenanceGraph, bU as ManifestEntity, bV as ManifestField, bW as ManifestFieldType, bX as ManifestGsi, bY as ManifestKey, bZ as ManifestRelation, b_ as ManifestTable, b$ as MembershipEffect, c0 as ModelRef, c1 as MutateMode, c2 as MutateOptions, c3 as MutateParallelResult, c4 as MutateTransactionResult, c5 as MutationBody, c6 as MutationDescriptorMap, c7 as MutationFragment, c8 as MutationInputProxy, c9 as MutationInputRef, ca as MutationIntent, cb as NumberParam, cc as OperationKind, cd as OperationSpec, ce as ParallelOpResult, cf as ParamKind, cg as ParamSpec, ch as ParamStructure, ci as PersistCtx, cj as PersistOrigin, ck as PlannedCommandMethod, cl as ProjectionMap, cm as ProjectionTransformOp, cn as PutOptions, co as QueryContractMethodSpec, cp as QueryEnvelopeResult, cq as QueryKeyOf, cr as QueryMethod, cs as QueryResult, ct as RangeConditionSpec, cu as ReadEnvelope, cv as ReadOpCtx, cw as ReadOpKind, cx as ReadOperationType, cy as ReadRouteDescriptor, cz as ReadRouteOptions, cA as ReadRouteResult, cB as RecordedCompose, cC as RelationBuilder, cD as RelationConsistency, cE as RelationLimitOptions, cF as RelationPattern, cG as RelationProjection, cH as RelationReadOptions, cI as RelationSelect, cJ as RelationSpec, cK as RelationUpdateMode, cL as RelationWriteOptions, cM as RequiresEffect, cN as Resolution, cO as RetryInfo, cP as RetryOperationKind, cQ as SPEC_VERSION, cR as SegmentSpec, cS as SegmentedKey, cT as SelectBuilder, cU as SelectOf, cV as SnapshotEffect, cW as StartingPosition, cX as StreamViewType, cY as StringParam, cZ as SubscribeHandler, c_ as SubscribeHandlers, c$ as TransactionContext, d0 as TransactionItemType, d1 as UniqueEffect, d2 as Updatable, d3 as UpdateOptions, d4 as ViewSourceSlice, d5 as WhenSpec, d6 as WriteCtx, d7 as WriteDescriptor, d8 as WriteEnvelope, d9 as WriteInput, da as WriteKind, db as WriteLifecyclePhase, dc as WriteMiddleware, dd as WriteOperationType, de as WriteRecorder, df as WriteResultProjection, dg as attachModelClass, dh as buildDeleteInput, di as buildMaintenanceGraph, dj as buildPutInput, dk as buildSubscribeHandler, dl as buildUpdateInput, dm as collectViewDefinitions, dn as compileFragment, dp as compileMutationPlan, dq as compileSingleFragmentPlan, dr as cond, ds as contractOfMethodSpec, dt as definePlan, du as entityWrites, dv as executeBatchGet, dw as executeBatchWrite, dx as executeCommandMethod, dy as executeDelete, dz as executeKeyedBatchGet, dA as executePut, dB as executeQueryMethod, dC as executeRangeFanout, dD as executeTransaction, dE as executeUpdate, dF as from, dG as getEntityWrites, dH as gsi, dI as identity, dJ as isColumn, dK as isCommandModelContract, dL as isCommandPlan, dM as isContractComposeNode, dN as isContractFromRef, dO as isContractKeyFieldRef, dP as isContractKeyRef, dQ as isContractParamRef, dR as isEntityWritesDefinition, dS as isKeySegment, dT as isLifecycleContract, dU as isMaintainTrigger, dV as isMutationFragment, dW as isMutationInputRef, dX as isParam, dY as isPlannedCommandMethod, dZ as isQueryModelContract, d_ as isRetryableError, d$ as isRetryableTransactionCancellation, e0 as k, e1 as key, e2 as lifecyclePhaseForIntent, e3 as maintainTrigger, e4 as mintContractKeyFieldRef, e5 as mintContractParamRef, e6 as mutation, e7 as param, e8 as preview, e9 as publicCommandModel, ea as publicQueryModel, eb as query, ec as resolveLifecycle, ed as wholeKeysSentinel } from './types-B9rJ1z3H.js';
 import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
 import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
 
@@ -356,6 +356,19 @@ declare class MetadataRegistry {
     static get(target: Function): EntityMetadata;
     static has(target: Function): boolean;
     static getAll(): Map<Function, EntityMetadata>;
+    /**
+     * Snapshot of the entities that are **already finalized**, WITHOUT triggering
+     * finalize on any pending entity (unlike {@link getAll}). This is the safe view
+     * for a cross-entity lint rule that runs *inside* `finalize`: eagerly
+     * finalizing the rest of the registry from within a finalize pass would
+     * re-enter (and duplicate) the in-progress entity's finalize. A whole-registry
+     * rule instead reasons over the already-finalized peers plus the entity
+     * currently being checked; any conflicting pair is caught when the later of the
+     * two finalizes (both are present by then).
+     *
+     * @internal — for cross-entity linter rules.
+     */
+    static getFinalized(): Map<Function, EntityMetadata>;
     static get linter(): Linter;
     static set linter(linter: Linter);
     /** Resets linter to the default built-in rule set. */
@@ -484,6 +497,48 @@ interface FieldDecorator<T> extends FieldDecoratorFn<T> {
  *   `literals` set.
  */
 declare function literal<const L extends string>(...values: readonly [L, ...L[]]): FieldDecoratorFn<L>;
+/**
+ * `@ttl` — the **DynamoDB Time-To-Live** field decorator (issue #172, Epic #167 —
+ * CFn generator C4). It marks the model's TTL attribute: the Number field holding
+ * the **epoch-seconds** expiry timestamp DynamoDB reads to auto-delete the item.
+ *
+ * ## Standalone, number-pinned (not composed with `@number`)
+ *
+ * `@ttl` is a **standalone** semantic decorator — it records the field's storage
+ * type (`dynamoType: 'N'`) itself, exactly as `@datetime` records `'S'` + a format
+ * and `@literal` records `'S'` + a literal set. It is NOT composed with `@number`
+ * (a `@number @ttl` stack). Two reasons:
+ *
+ *  1. **A valid TTL attribute is always a Number** (epoch seconds) — there is no
+ *     string/boolean TTL — so the storage type is not a free choice the author
+ *     should have to (re)state. Folding `'N'` into `@ttl` removes the redundant
+ *     second decorator and the ordering/consistency question a two-decorator stack
+ *     would raise (which wins if they disagreed?).
+ *  2. It matches the module idiom: every semantic decorator here is self-contained
+ *     and pins exactly one storage type; none composes with another.
+ *
+ * ## Loud-reject (the most-feared silent-drop class in this repo)
+ *
+ *  - **Non-number field → compile error.** The decorator is pinned to `number`
+ *    (its `context` is `ClassFieldDecoratorContext<unknown, number | undefined>`),
+ *    so `@ttl expiresAt!: string` fails to type-check — the SAME cross-type
+ *    mechanism that makes `@number age!: string` an error. A TTL on a non-Number
+ *    attribute can never be declared (DynamoDB would silently never expire it).
+ *  - **More than one `@ttl` per (physical) table → throws.** DynamoDB allows
+ *    exactly one TTL attribute per table. A second `@ttl` on the same model throws
+ *    at `@model` registration; two `@ttl` fields on DIFFERENT entities sharing one
+ *    physical table throw at manifest build (where all table siblings are known).
+ *
+ * ## Runtime behaviour
+ *
+ * A `@ttl` field is a plain stored Number at runtime — no special serialization,
+ * hydration, or key handling (it is not a key attribute). The decorator only
+ * records metadata (`dynamoType: 'N'`, `ttl: true`); the TTL *effect* is a table
+ * property DynamoDB applies, emitted into the generated CloudFormation
+ * `TimeToLiveSpecification` (never into `AttributeDefinitions`, which holds key
+ * attributes only). So it needs no runtime-serialization conformance change.
+ */
+declare const ttl: FieldDecoratorFn<number>;
 declare const string: FieldDecorator<string>;
 declare const number: FieldDecorator<number>;
 declare const boolean: FieldDecorator<boolean>;
@@ -868,6 +923,51 @@ declare function count(): AggregateValue;
  */
 declare function max(field: string): AggregateValue;
 
+/**
+ * `@cdcProjected()` — mark a source model **CDC-parseable** (issue #153).
+ *
+ * ## What it is
+ *
+ * External projection means projecting a source model's changes onto an external
+ * sink (BigQuery / OpenSearch / …) over CDC (DynamoDB Streams). graphddb owns only
+ * the **parse → typed record** contract; the sink write / dedup / delivery live in
+ * the consumer's CDC infrastructure, OUTSIDE the boundary (see
+ * `docs/cdc-projection.md`). `@cdcProjected()` is the model-level opt-in that
+ * enables that contract on a model:
+ *
+ * - `Model.fromChange(event)` (the pure `(event) => [old, new]` typed mapper) is
+ *   gated on it — calling it on an un-annotated model throws (and is a compile
+ *   error via the type surface);
+ * - `DDBModel.subscribe(handlers)` routes CDC events only to `@cdcProjected` models;
+ * - the codegen reads the flag to emit the `CdcModelRegistry` module augmentation
+ *   that types `subscribe`'s handlers by model name.
+ *
+ * ## No runtime side effect
+ *
+ * The decorator carries NO runtime — it does not subscribe, write, capture, or hook
+ * anything. It only flips a capability bit
+ * ({@link import('../metadata/types.js').EntityMetadata.cdcProjected}) on the model's
+ * metadata. Like `@maintainedFrom`, it is a CLASS-LEVEL decorator that runs BEFORE
+ * the topmost `@model` (TC39 bottom-up class-decorator ordering), so it pushes into
+ * the module-level collector and `@model` drains it. Stacking it above or below
+ * other class decorators carries no meaning.
+ *
+ * @example
+ * ```ts
+ * @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;
+ *   @datetime updatedAt!: Date;
+ * }
+ * ```
+ */
+declare function cdcProjected(): (_target: Function, _context: ClassDecoratorContext) => void;
+
 declare class TableMapping {
     private static mapping;
     static set(mapping: Record<string, string>): void;
@@ -1516,6 +1616,46 @@ declare function createMaintenanceDrain(opts?: MaintenanceDrainOptions): Mainten
  */
 declare function createMaintenanceDrainHandler(opts?: MaintenanceDrainOptions): ChangeHandler;
 
+/**
+ * `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];
+
 /**
  * Per-key cursor envelope for batched `range` (`list`) contract methods (issue
  * #62, CQRS single-service runtime; spec `docs/cqrs-contract.md`,
@@ -1608,6 +1748,13 @@ declare function decodePerKeyCursor(cursor: string, expectedKey: Record<string,
  * unaffected. query-boundary is excluded because it flags non-unique GSIs which
  * are valid for list() operations; boundary enforcement is handled at runtime by
  * the planner's boundary-check.
+ *
+ * Also includes cfn-schema-consistency (issue #169): a whole-table validator
+ * that rejects entities sharing a physical table with an ambiguous base
+ * KeySchema, inconsistently-shared GSI index names, or more than 20 unioned
+ * GSIs — the CFn deploy-consistency user-error class, caught statically at
+ * finalize. It is additive: a single entity on its own table with ≤ 20 GSIs is
+ * never affected.
  */
 declare function createDefaultLinter(): Linter;
 
@@ -3003,4 +3150,4 @@ declare function assertBundleSerializable(bundle: BridgeBundle): void;
  */
 declare function buildBridgeBundle(queries?: DefinitionMap, commands?: DefinitionMap, registry?: typeof MetadataRegistry, transactions?: Record<string, TransactionDefinition>, contractInputs?: ContractInputs): BridgeBundle;
 
-export { AggregateOptions, AggregateValue, type AnyModelContract, AnyOperationDefinition, BATCH_GET_MAX_KEYS, BATCH_WRITE_MAX_ITEMS, BatchExecOptions, BatchGetExecInput, BatchWriteExecItem, BridgeBundle, type BuiltContracts, CdcEmulator, CdcEmulatorOptions, ChangeEvent, ChangeHandler, ClientManager, type CollectParams, CommandMethodSpec, CommandModelContract, CommandSpec, ConcurrentRecomputeRef, type ConditionExpressionResult, ConditionInput, ConditionSpec, type ContextOwnership, type ContextOwnershipMap, ContextSpec, type ContractBoundaryViolation, type ContractInputs, type ContractMap, type ContractN1Violation, ContractSpec, CtxModel, DDBModel, DefinitionMap, DeleteInput, type DriftReport, DynamoDBOperation, DynamoExecutor, DynamoType, EDGE_WRITES_MARKER, type EdgeLifecycle, type EdgeWriteDeclaration, type EdgeWriteRecorder, type EdgeWritesDefinition, EntityMetadata, EntityRef, EventLog, ExecutionPlan, Executor, ExecutorResult, type ExplainInput, FaultSpec, FieldMetadata, FieldOptions, type FilterExpressionResult, GsiDefinition, type HasManyVersionedCallback, type HasManyVersionedOptions, type HasOneVersionedCallback, type HasOneVersionedOptions, Item, KeyDefinition, type LintResult, type LintRule, Linter, type ListInput, type ListOptions, MAINT_OUTBOX_PK_PREFIX, MAX_TRANSACT_ITEMS, MaintainConsistency, MaintainEffect, MaintainEvent, MaintainUpdateMode, type MaintainedFromCallback, type MaintainedFromOptions, MaintenanceDrain, type MaintenanceDrainOptions, type MaintenanceRebuildOptions, MaintenanceRebuilder, Manifest, MembershipPredicate, MembershipPredicateOp, MetadataRegistry, Middleware, type ModelOptions, ModelStatic, OLD_VALUE_NAMESPACE, OperationDefinition, OperationsDocument, Param, ParamDescriptor, type Parameterize, PartialQueryKeyOf, type PerKeyCursorEnvelope, type PlanInput, PrimaryKeyOf, type ProjectionResult, ProjectionTransform, type ProjectionValue, PutInput, QueryMethodSpec, QueryModelContract, type QueryOptions$1 as QueryOptions, QuerySpec, RawCondition, ReadExecOptions, ReadParams, ReadRequestCtx, ReadRequestKind, type RebuildResult, RelationMetadata, RelationOptions, type RelationTraversalOptions, ReplayOptions, RequestContext, ResolvedKey, RetryOverride, RetryPolicy, RetryingExecutor, SelectableOf, type SelfProxy, type SelfRef, ShardId, type SourceProxy, type SourceRef, TableMapping, TransactWriteExecItem, type TransactionDefinition, TransactionItemSpec, type TransactionParamShape, type TransactionRef, TransactionSpec, type TxConditionCheckOptions, type TxForEachInstruction, type TxForEachOptions, type TxInstruction, type TxRecorder, type TxWriteInstruction, type TxWriteOptions, UniqueQueryKeyOf, type UpdateExpressionResult, UpdateInput, type VersionedHistoryOptions, type VersionedLatestOptions, ViewDefinition, type WhenComparison, WriteDefinitionOptions, WriteExecOptions, WriteResult, aggregate, assertBundleSerializable, assertContractBoundaries, assertContractN1Safe, assertJsonSerializable, assertSupportedCondition, belongsTo, binary, boolean, buildBridgeBundle, buildConditionExpression, buildContexts, buildContracts, buildManifest, buildOperations, buildProjection, buildQuerySpec, buildTransactionSpec, buildTransactions, buildUpdateExpression, collectContractBoundaryViolations, collectContractN1Violations, compileFilterExpression, count, createCdcEmulator, createDefaultLinter, createMaintenanceDrain, createMaintenanceDrainHandler, createMaintenanceRebuilder, datetime, decodeCursor, decodePerKeyCursor, defineCommands, defineDelete, defineList, definePut, defineQueries, defineQuery, defineTransaction, defineTransactions, defineUpdate, deriveEdgeWriteItems, deriveEdgeWriteItemsFor, deriveModelEdgeWriteItems, derivePrefix, detectRelationFields, edgeWrites, embedded, encodeCursor, encodePerKeyCursor, evaluateFilter, execute, executeDeclarativeTransaction, executeExplain, executeList, executeQuery, expandTransaction, field, getEdgeWrites, getImplicitKeyFields, gsiAmbiguityRule, hasMany, hasOne, hydrate, isEdgeWritesDefinition, isSelectBuilder, isTransactionRef, list, literal, maintainedFrom, map, max, missingGsiRule, model, noScanRule, number, numberSet, plan, queryBoundaryRule, relationDepthRule, requireLimitRule, resolveKey, resolveRelations, serializeContractKey, serializeFieldValue, string, stringSet, validateDepth, validateGsiAmbiguity, when, whenMember };
+export { AggregateOptions, AggregateValue, type AnyModelContract, AnyOperationDefinition, BATCH_GET_MAX_KEYS, BATCH_WRITE_MAX_ITEMS, BatchExecOptions, BatchGetExecInput, BatchWriteExecItem, BridgeBundle, type BuiltContracts, CdcEmulator, CdcEmulatorOptions, ChangeEvent, ChangeHandler, ClientManager, type CollectParams, CommandMethodSpec, CommandModelContract, CommandSpec, ConcurrentRecomputeRef, type ConditionExpressionResult, ConditionInput, ConditionSpec, type ContextOwnership, type ContextOwnershipMap, ContextSpec, type ContractBoundaryViolation, type ContractInputs, type ContractMap, type ContractN1Violation, ContractSpec, CtxModel, DDBModel, DefinitionMap, DeleteInput, type DriftReport, DynamoDBOperation, DynamoExecutor, DynamoType, EDGE_WRITES_MARKER, type EdgeLifecycle, type EdgeWriteDeclaration, type EdgeWriteRecorder, type EdgeWritesDefinition, EntityMetadata, EntityRef, EventLog, ExecutionPlan, Executor, ExecutorResult, type ExplainInput, FaultSpec, FieldMetadata, FieldOptions, type FilterExpressionResult, GsiDefinition, type HasManyVersionedCallback, type HasManyVersionedOptions, type HasOneVersionedCallback, type HasOneVersionedOptions, Item, KeyDefinition, type LintResult, type LintRule, Linter, type ListInput, type ListOptions, MAINT_OUTBOX_PK_PREFIX, MAX_TRANSACT_ITEMS, MaintainConsistency, MaintainEffect, MaintainEvent, MaintainUpdateMode, type MaintainedFromCallback, type MaintainedFromOptions, MaintenanceDrain, type MaintenanceDrainOptions, type MaintenanceRebuildOptions, MaintenanceRebuilder, Manifest, MembershipPredicate, MembershipPredicateOp, MetadataRegistry, Middleware, type ModelOptions, ModelStatic, OLD_VALUE_NAMESPACE, OperationDefinition, OperationsDocument, Param, ParamDescriptor, type Parameterize, PartialQueryKeyOf, type PerKeyCursorEnvelope, type PlanInput, PrimaryKeyOf, type ProjectionResult, ProjectionTransform, type ProjectionValue, PutInput, QueryMethodSpec, QueryModelContract, type QueryOptions$1 as QueryOptions, QuerySpec, RawCondition, ReadExecOptions, ReadParams, ReadRequestCtx, ReadRequestKind, type RebuildResult, RelationMetadata, RelationOptions, type RelationTraversalOptions, ReplayOptions, RequestContext, ResolvedKey, RetryOverride, RetryPolicy, RetryingExecutor, SelectableOf, type SelfProxy, type SelfRef, ShardId, type SourceProxy, type SourceRef, TableMapping, TransactWriteExecItem, type TransactionDefinition, TransactionItemSpec, type TransactionParamShape, type TransactionRef, TransactionSpec, type TxConditionCheckOptions, type TxForEachInstruction, type TxForEachOptions, type TxInstruction, type TxRecorder, type TxWriteInstruction, type TxWriteOptions, UniqueQueryKeyOf, type UpdateExpressionResult, UpdateInput, type VersionedHistoryOptions, type VersionedLatestOptions, ViewDefinition, type WhenComparison, WriteDefinitionOptions, WriteExecOptions, WriteResult, aggregate, assertBundleSerializable, assertContractBoundaries, assertContractN1Safe, assertJsonSerializable, assertSupportedCondition, belongsTo, binary, boolean, buildBridgeBundle, buildConditionExpression, buildContexts, buildContracts, buildManifest, buildOperations, buildProjection, buildQuerySpec, buildTransactionSpec, buildTransactions, buildUpdateExpression, cdcProjected, collectContractBoundaryViolations, collectContractN1Violations, compileFilterExpression, count, createCdcEmulator, createDefaultLinter, createMaintenanceDrain, createMaintenanceDrainHandler, createMaintenanceRebuilder, datetime, decodeCursor, decodePerKeyCursor, defineCommands, defineDelete, defineList, definePut, defineQueries, defineQuery, defineTransaction, defineTransactions, defineUpdate, deriveEdgeWriteItems, deriveEdgeWriteItemsFor, deriveModelEdgeWriteItems, derivePrefix, detectRelationFields, edgeWrites, embedded, encodeCursor, encodePerKeyCursor, evaluateFilter, execute, executeDeclarativeTransaction, executeExplain, executeList, executeQuery, expandTransaction, field, getEdgeWrites, getImplicitKeyFields, gsiAmbiguityRule, hasMany, hasOne, hydrate, isEdgeWritesDefinition, isSelectBuilder, isTransactionRef, list, literal, maintainedFrom, map, max, missingGsiRule, model, noScanRule, number, numberSet, parseChange, plan, queryBoundaryRule, relationDepthRule, requireLimitRule, resolveKey, resolveRelations, serializeContractKey, serializeFieldValue, string, stringSet, ttl, validateDepth, validateGsiAmbiguity, when, whenMember };

package/dist/index.js

@@ -51,7 +51,6 @@ import {
   from,
   getEdgeWrites,
   getImplicitKeyFields,
-  hydrate,
   isCommandModelContract,
   isCommandPlan,
   isContractComposeNode,
@@ -64,7 +63,6 @@ import {
   isMutationInputRef,
   isPlannedCommandMethod,
   isQueryModelContract,
-  isSelectBuilder,
   isTransactionRef,
   mapWithConcurrency,
   mintContractKeyFieldRef,
@@ -79,7 +77,7 @@ import {
   validateDepth,
   when,
   wholeKeysSentinel
-} from "./chunk-G5RWWBAL.js";
+} from "./chunk-FI63YKK5.js";
 import {
   CdcEmulator,
   MAINT_OUTBOX_PK_PREFIX,
@@ -91,7 +89,7 @@ import {
   orderAndTrimCollection,
   pathField,
   projectFrom
-} from "./chunk-BROCT574.js";
+} from "./chunk-EMJHTUA4.js";
 import {
   BATCH_GET_MAX_KEYS,
   BATCH_WRITE_MAX_ITEMS,
@@ -112,6 +110,7 @@ import {
   buildDeleteInput,
   buildMaintenanceGraph,
   buildPutInput,
+  buildSubscribeHandler,
   buildUpdateExpression,
   buildUpdateInput,
   collapseSameKeyItems,
@@ -129,6 +128,7 @@ import {
   getEntityWrites,
   gsi,
   gsiAmbiguityRule,
+  hydrate,
   identity,
   isColumn,
   isEntityWritesDefinition,
@@ -139,6 +139,7 @@ import {
   isRawCondition,
   isRetryableError,
   isRetryableTransactionCancellation,
+  isSelectBuilder,
   k,
   key,
   lifecyclePhaseForIntent,
@@ -146,6 +147,7 @@ import {
   missingGsiRule,
   noScanRule,
   param,
+  parseChange,
   preview,
   relationDepthRule,
   requireLimitRule,
@@ -154,7 +156,7 @@ import {
   resolveModelClass,
   segmentFieldNames,
   serializeFieldValue
-} from "./chunk-CPTV3H2U.js";
+} from "./chunk-B3GWIWT6.js";
 
 // src/metadata/prefix.ts
 function derivePrefix(customPrefix, className) {
@@ -206,6 +208,7 @@ var pendingEmbedded = [];
 var pendingRelations = [];
 var pendingAggregates = [];
 var pendingMaintainedFrom = [];
+var pendingCdcProjected = false;
 function collectField(field2) {
   pendingFields.push(field2);
 }
@@ -221,6 +224,9 @@ function collectAggregate(aggregate2) {
 function collectMaintainedFrom(decl) {
   pendingMaintainedFrom.push(decl);
 }
+function collectCdcProjected() {
+  pendingCdcProjected = true;
+}
 function drainFields() {
   const result = pendingFields;
   pendingFields = [];
@@ -246,6 +252,11 @@ function drainMaintainedFrom() {
   pendingMaintainedFrom = [];
   return result;
 }
+function drainCdcProjected() {
+  const result = pendingCdcProjected;
+  pendingCdcProjected = false;
+  return result;
+}
 
 // src/decorators/model.ts
 function model(options) {
@@ -255,6 +266,7 @@ function model(options) {
     const relations = drainRelations();
     const aggregates = drainAggregates();
     const maintainedFrom2 = drainMaintainedFrom();
+    const cdcProjected2 = drainCdcProjected();
     const prefix = derivePrefix(options.prefix, context.name);
     const kind = options.kind ?? "entity";
     if (kind === "entity" && maintainedFrom2.length > 0) {
@@ -267,6 +279,13 @@ function model(options) {
         `@model on '${String(context.name)}': \`kind: '${kind}'\` declares a maintained view but no \`@maintainedFrom(...)\` source is stacked. A view with no source is maintained by nothing \u2014 add at least one \`@maintainedFrom\` decorator.`
       );
     }
+    const ttlFields = fields.filter((f) => f.ttl === true);
+    if (ttlFields.length > 1) {
+      throw new Error(
+        `@model on '${String(context.name)}': ${ttlFields.length} \`@ttl\` fields (${ttlFields.map((f) => `'${f.propertyName}'`).join(", ")}) are declared, but DynamoDB allows exactly one TTL attribute per table. Mark a single field \`@ttl\`.`
+      );
+    }
+    const ttlAttribute = ttlFields.length === 1 ? ttlFields[0].propertyName : void 0;
     MetadataRegistry.register(target, {
       tableName: options.table,
       prefix,
@@ -278,7 +297,9 @@ function model(options) {
       embeddedFields,
       kind,
       ...options.description !== void 0 ? { description: options.description } : {},
-      maintainedFrom: maintainedFrom2
+      ...cdcProjected2 ? { cdcProjected: cdcProjected2 } : {},
+      maintainedFrom: maintainedFrom2,
+      ...ttlAttribute !== void 0 ? { ttlAttribute } : {}
     });
   };
 }
@@ -328,6 +349,13 @@ function literal(...values) {
     });
   };
 }
+var ttl = (_value, context) => {
+  collectField({
+    propertyName: String(context.name),
+    dynamoType: "N",
+    ttl: true
+  });
+};
 var string = createFieldDecorator("S");
 var number = createFieldDecorator("N");
 var boolean = createFieldDecorator("BOOL");
@@ -659,6 +687,13 @@ function maintainedFrom(source, callback) {
   };
 }
 
+// src/decorators/cdc-projected.ts
+function cdcProjected() {
+  return function(_target, _context) {
+    collectCdcProjected();
+  };
+}
+
 // src/operations/declarative-transaction.ts
 var PLACEHOLDER_RE = /\{[^{}]+\}/g;
 function resolveTemplate(template, params, element) {
@@ -1848,10 +1883,12 @@ export {
   buildProjection,
   buildPutInput,
   buildQuerySpec,
+  buildSubscribeHandler,
   buildTransactionSpec,
   buildTransactions,
   buildUpdateExpression,
   buildUpdateInput,
+  cdcProjected,
   collectContractBoundaryViolations,
   collectContractN1Violations,
   collectViewDefinitions,
@@ -1958,6 +1995,7 @@ export {
   number,
   numberSet,
   param,
+  parseChange,
   plan,
   preview,
   publicCommandModel,
@@ -1973,6 +2011,7 @@ export {
   serializeFieldValue,
   string,
   stringSet,
+  ttl,
   validateDepth,
   validateGsiAmbiguity,
   when,

package/dist/testing/index.d.ts

@@ -1,4 +1,4 @@
-import { E as Executor, D as DynamoDBOperation, R as ReadExecOptions, a as ExecutorResult, B as BatchGetExecInput, P as PutInput, W as WriteExecOptions, b as WriteResult, U as UpdateInput, c as DeleteInput, d as BatchWriteExecItem, e as BatchExecOptions, T as TransactWriteExecItem, M as ModelStatic, f as DDBModel, C as ChangeEvent } from '../types-BWOrWcbd.js';
+import { E as Executor, D as DynamoDBOperation, R as ReadExecOptions, a as ExecutorResult, B as BatchGetExecInput, P as PutInput, W as WriteExecOptions, b as WriteResult, U as UpdateInput, c as DeleteInput, d as BatchWriteExecItem, e as BatchExecOptions, T as TransactWriteExecItem, M as ModelStatic, f as DDBModel, C as ChangeEvent } from '../types-B9rJ1z3H.js';
 import '@aws-sdk/client-dynamodb';
 
 /**

package/dist/testing/index.js

@@ -1,12 +1,12 @@
 import {
   createCdcEmulator
-} from "../chunk-BROCT574.js";
+} from "../chunk-EMJHTUA4.js";
 import {
   ClientManager,
   MetadataRegistry,
   TableMapping,
   resolveModelClass
-} from "../chunk-CPTV3H2U.js";
+} from "../chunk-B3GWIWT6.js";
 
 // src/memory/memory-store.ts
 function deepClone(value) {