graphddb 0.4.2 → 0.5.0

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-B-F7jw9f.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-B-F7jw9f.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>;
@@ -1608,6 +1663,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 +3065,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, 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, ttl, validateDepth, validateGsiAmbiguity, when, whenMember };

package/dist/index.js

@@ -79,7 +79,7 @@ import {
   validateDepth,
   when,
   wholeKeysSentinel
-} from "./chunk-G5RWWBAL.js";
+} from "./chunk-J5A665UW.js";
 import {
   CdcEmulator,
   MAINT_OUTBOX_PK_PREFIX,
@@ -91,7 +91,7 @@ import {
   orderAndTrimCollection,
   pathField,
   projectFrom
-} from "./chunk-BROCT574.js";
+} from "./chunk-7NPG5R7O.js";
 import {
   BATCH_GET_MAX_KEYS,
   BATCH_WRITE_MAX_ITEMS,
@@ -154,7 +154,7 @@ import {
   resolveModelClass,
   segmentFieldNames,
   serializeFieldValue
-} from "./chunk-CPTV3H2U.js";
+} from "./chunk-FMJIWFIS.js";
 
 // src/metadata/prefix.ts
 function derivePrefix(customPrefix, className) {
@@ -267,6 +267,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 +285,8 @@ function model(options) {
       embeddedFields,
       kind,
       ...options.description !== void 0 ? { description: options.description } : {},
-      maintainedFrom: maintainedFrom2
+      maintainedFrom: maintainedFrom2,
+      ...ttlAttribute !== void 0 ? { ttlAttribute } : {}
     });
   };
 }
@@ -328,6 +336,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");
@@ -1973,6 +1988,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-B-F7jw9f.js';
 import '@aws-sdk/client-dynamodb';
 
 /**

package/dist/testing/index.js

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

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

@@ -3126,6 +3126,21 @@ interface ManifestEntity {
      * manifest. Surfaces as the generated Python class docstring.
      */
     readonly description?: string;
+    /**
+     * The physical attribute name of the model's DynamoDB **Time-To-Live** field,
+     * when one is declared via `@ttl` (issue #172, Epic #167 — CFn generator C4).
+     * Unlike the maintenance/stream signals (a maintenance-IR concern kept OFF the
+     * manifest), TTL is a **physical schema** fact, and the CloudFormation emitter
+     * consumes the manifest — so the TTL attribute name flows here and the emitter
+     * renders `TimeToLiveSpecification { AttributeName: <this>, Enabled: true }`. The
+     * attribute is deliberately NOT added to the table's key `AttributeDefinitions`
+     * (that list holds ONLY key/index attributes; `TimeToLiveSpecification` legitimately
+     * names a non-key attribute). **Absent** when the model declares no `@ttl`, so a
+     * TTL-free model serializes byte-identically to the pre-#172 manifest (backward
+     * compatible). DynamoDB permits exactly one TTL attribute per physical table; the
+     * single-per-table rule is enforced at manifest build.
+     */
+    readonly ttlAttribute?: string;
 }
 interface ManifestTable {
     readonly physicalName: string;
@@ -6230,6 +6245,20 @@ interface FieldMetadata {
      * `@number`, …), so plain fields are byte-for-byte unchanged (backward compat).
      */
     literals?: readonly string[];
+    /**
+     * For an `@ttl` field (issue #172, Epic #167 — CFn generator C4) — marks this
+     * field as the model's **DynamoDB Time-To-Live** attribute. `@ttl` is a
+     * standalone semantic decorator pinned to `number` (it records `dynamoType: 'N'`
+     * itself, so `@ttl expiresAt!: string` is a compile error), because DynamoDB TTL
+     * requires a Number attribute holding **epoch seconds**. It is a **physical
+     * schema** fact (unlike the maintenance signals kept off the manifest): the flag
+     * flows through {@link EntityMetadata} into `manifest.json`
+     * ({@link ManifestEntity.ttlAttribute}), which the CloudFormation emitter consumes
+     * to render `TimeToLiveSpecification`. DynamoDB allows exactly one TTL attribute
+     * per table, enforced loudly at model registration (`@model`). `undefined` for
+     * every other field decorator, so non-TTL fields are byte-for-byte unchanged.
+     */
+    ttl?: boolean;
 }
 
 /**
@@ -6530,6 +6559,19 @@ interface EntityMetadata {
      * Absent / empty for a plain entity.
      */
     maintainedFrom?: MaintainedFromMetadata[];
+    /**
+     * 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
+     * Number attribute holding epoch seconds; `@model` derives this from the (unique)
+     * field carrying {@link FieldMetadata.ttl} and throws if more than one field on the
+     * SAME model is `@ttl` (the cross-entity, same-physical-table single-TTL rule is
+     * enforced downstream, at manifest build, where all entities on a table are known).
+     * A non-key field's physical attribute name is its property name, so this is the
+     * `@ttl` field's property name. Propagated to the manifest
+     * ({@link ManifestEntity.ttlAttribute}) — the SSoT the CloudFormation emitter reads
+     * to render `TimeToLiveSpecification`. Absent when the model declares no `@ttl`.
+     */
+    ttlAttribute?: string;
 }
 
 /**

package/docs/cdc-emulator.md

@@ -0,0 +1,203 @@
+# CDC Emulator
+
+The CDC (Change Data Capture) emulator produces DynamoDB-Streams-equivalent change events from GraphDDB writes and delivers them to a consumer under a deterministic, fault-injectable delivery contract. It exists to drive and verify stream-based logic — incremental aggregation in particular (see the [Aggregate Tree Pattern](../examples/aggregate-tree-pattern/README.md)) — locally and in CI.
+
+The emulator is **dev/test only**. DynamoDB Local does not support Streams, so there is no standard way to exercise stream consumers off-cloud. The emulator fills that gap. Its `ChangeEvent` type and delivery contract mirror real DynamoDB Streams (`NEW_AND_OLD_IMAGES`), so a consumer written against the emulator runs unchanged against real Streams in production.
+
+The emulator is responsible only for **producing, delivering, faulting, and replaying change events**. It performs no aggregation; aggregate logic lives entirely in the consumer.
+
+## Scope
+
+| In scope | Out of scope |
+|---|---|
+| Capturing writes and producing `ChangeEvent`s | Running aggregations (consumer's responsibility) |
+| OldImage / NewImage attachment | Faithful reproduction of real Streams internals (shard splits, iterator age) |
+| Per-shard ordering and batched delivery | Cross-region / GSI streams, TTL-delete events |
+| Fault injection (duplicate, reorder, delay, drop, partial-batch failure) | A user-facing public write hook |
+| Record / replay | Production use |
+
+## The `ChangeEvent` type
+
+`ChangeEvent` is owned by the `cdc` module; `core` never references it. The shape mirrors a DynamoDB Streams record under the `NEW_AND_OLD_IMAGES` view, which is the only view supported — incremental aggregation requires both images.
+
+```ts
+type StreamViewType = 'NEW_AND_OLD_IMAGES';
+type ChangeEventName = 'INSERT' | 'MODIFY' | 'REMOVE';
+
+interface ChangeEvent<T = Record<string, unknown>> {
+  eventName: ChangeEventName;
+  table: string;
+  model?: string;                  // resolved model name when known
+  keys: { pk: string; sk: string };
+  oldImage?: T;                    // present for MODIFY / REMOVE
+  newImage?: T;                    // present for INSERT / MODIFY
+  approximateCreationTime: string; // ISO 8601, derived from the clock
+  sequenceNumber: string;          // monotonic within a shard, zero-padded
+  shardId: string;                 // partition = hash(pk)
+}
+
+interface ChangeBatch<T = Record<string, unknown>> {
+  records: ChangeEvent<T>[];       // same-shard records in sequenceNumber order
+}
+
+interface BatchResult {
+  batchItemFailures?: string[];    // sequenceNumbers the consumer failed to process
+}
+
+type ChangeHandler = (batch: ChangeBatch) => Promise<BatchResult | void>;
+```
+
+`eventName` is derived from the write: a `delete` yields `REMOVE`; a `put`/`update` yields `MODIFY` when a prior image existed, otherwise `INSERT`. `sequenceNumber` is the per-shard monotonic counter rendered as a 20-digit zero-padded string so lexicographic order equals numeric order. `approximateCreationTime` is derived from the active clock (virtual or real).
+
+A consumer derives a delta from `oldImage`/`newImage` and may use `approximateCreationTime` as the source change time.
+
+## Capture seam
+
+GraphDDB captures writes through an internal, non-exported seam in `core`. The write paths (`executePut`/`Update`/`Delete`/`batch`/`transaction`) call `captureWrite(record)` **after a successful write**. The seam carries only a minimal `RawWriteRecord` (`table`, `model?`, `op`, `keys`, `newItem?`, `oldItem?`); `core` knows nothing of images, sequence numbers, or shards.
+
+- The seam is `@internal` and is **not** re-exported from `src/index.ts`. It is the private internal mechanism, distinct from any user-facing hook (which is out of scope). The dependency direction is always `core ← cdc`; `core` does not import the cdc module, so there is no cycle.
+- `ChangeCaptureRegistry` (core-owned, `@internal`) supports multiple subscribers via `register(subscriber): Unsubscribe`. With zero subscribers the seam is a no-op, so there is zero overhead when nothing is listening.
+- A pre-write image (`ReturnValues: ALL_OLD`) is requested only when the model is stream-enabled **and** a subscriber is live, so the OldImage cost is never paid when nobody is listening.
+- Writes that did not actually land (e.g. `ConditionalCheckFailedException`) are not captured.
+- Capture failures are isolated: a throwing subscriber neither fails the originating write nor blocks other subscribers (errors are swallowed at the seam).
+
+The cdc module registers as one subscriber and maps each `RawWriteRecord` to a `ChangeEvent`, assigning `shardId`, `sequenceNumber`, and `approximateCreationTime`. Stream enablement is opt-in per model: each class in `opts.models` is stream-enabled on construction (`ChangeCaptureRegistry.enableStream`) and disabled on `close()`. When `models` is provided, records whose resolved model name is not in the set are dropped; a record carrying no model name is emitted.
+
+## Delivery contract
+
+- **Sharding.** `shardId = hash(pk) % shardCount` (FNV-1a, default `shardCount` 8). All events for one partition key land in the same shard.
+- **Per-shard ordering.** Within a shard, records are delivered in ascending `sequenceNumber`. Order across shards is independent.
+- **Batching.** Records are delivered in batches of up to `batchSize` (default 100) per shard.
+- **At-least-once.** Duplicate delivery is permitted and is reproducible via fault injection.
+- **Checkpoint / resume.** Each shard tracks the last successfully checkpointed sequence number, available via `checkpoints()`. The checkpoint advances only over the **contiguous prefix** of acked sequences (`ReportBatchItemFailures` semantics): it never moves past an un-acked record awaiting redelivery, so a resume cannot skip a record.
+- **Partial-batch failure.** The consumer returns the `sequenceNumber`s it failed to process in `BatchResult.batchItemFailures`. Successful records are checkpointed; failed records are redelivered, re-sorted into ascending order so per-shard ordering is preserved.
+- **Dead-letter queue.** A record that fails more than `maxRetries` times (default 3) is moved to the dead-letter buffer, available via `deadLetters()`.
+
+## Modes
+
+The `mode` option selects when events are delivered.
+
+| Mode | Use | Delivery timing |
+|---|---|---|
+| `inline` | Unit tests | Delivered automatically after each capture. The capture seam is synchronous; the async delivery is chained onto an internal promise that callers await via `flush()`. |
+| `queued` | Time-dependent behavior (throttle, sweep period, staleness) | Buffered. Delivery is driven by `pump()` or by advancing the virtual clock with `advanceClock()`. |
+| `record` | Capture a log without delivering | Events are recorded but not delivered; obtain the log with `record()`. |
+| `replay` | Replay-equivalence verification | Delivery is driven by `replay(log, opts?)`. |
+
+Every mode records events into an internal log, so `record()` and `replay()` are available regardless of mode.
+
+## Virtual clock
+
+The `clock` option is `'real'` or `'virtual'`; the default is `'virtual'` for `queued` mode and `'real'` otherwise. Under the virtual clock, time advances only through `advanceClock(ms)`, which moves the clock forward and delivers every record whose due time has arrived. `now()` returns the current virtual time in milliseconds since the emulator epoch (`2020-01-01T00:00:00Z`), and `approximateCreationTime` is derived from it. This makes throttle period, sweep period, and staleness behavior deterministic without depending on wall-clock time. `advanceClock()` throws if the clock is not virtual.
+
+## Fault injection
+
+Faults are configured via `fault(spec)` (the spec is merged into the current one). All randomness routes through a seeded PRNG (`seed`, default 1), so a given seed reproduces the exact same delivery — including duplicates, reorderings, delays, and failures.
+
+```ts
+interface FaultSpec {
+  duplicate?: number;             // probability a delivered record is delivered again
+  reorder?: boolean;              // shuffle within-shard order on delivery
+  delay?: { min: number; max: number }; // per-record virtual-time delivery delay (ms); requires queued mode
+  dropThenRedeliver?: number;     // probability a record is dropped on first delivery, then redelivered
+  partialBatchFailure?: number;   // probability a record is reported as a partial-batch failure
+}
+```
+
+`reorder` deliberately violates the within-shard ordering guarantee to exercise a consumer's invariant detection. `delay` withholds a record until the virtual clock reaches its due time.
+
+### Concurrent-recompute injection
+
+To stage a mark-versus-recompute race (the false-clean race), the harness arms two hooks:
+
+```ts
+emulator.injectConcurrentRecompute({ ref: 'Parent#p1' });   // which ref to race
+emulator.onConcurrentRecompute((ref, event) => { /* run the recompute */ });
+```
+
+Once both are set, the emulator invokes the registered recompute callback for each record immediately before that record reaches the consumer, deterministically interleaving the recompute with the consumer's mark. `injectConcurrentRecompute` alone records the ref; `onConcurrentRecompute` supplies the actual recompute and arms the race.
+
+## API
+
+```ts
+createCdcEmulator(opts?: CdcEmulatorOptions): CdcEmulator
+
+class CdcEmulator {
+  subscribe(handler: ChangeHandler): Unsubscribe;
+  flush(): Promise<void>;                 // await inline-mode deliveries
+  pump(maxBatches?: number): Promise<void>;
+  advanceClock(ms: number): Promise<void>;
+  now(): number;
+  fault(spec: FaultSpec): void;
+  injectConcurrentRecompute(ref: ConcurrentRecomputeRef): void;
+  onConcurrentRecompute(hook: (ref, event) => void | Promise<void>): void;
+  record(): EventLog;
+  replay(log: EventLog, opts?: ReplayOptions): Promise<void>;
+  checkpoints(): Record<ShardId, string>;
+  deadLetters(): ChangeEvent[];
+  reset(): void;                          // reset delivery state and re-seed (keeps subscription + opt-in)
+  close(): void;                          // detach from the seam, disable model streaming
+}
+```
+
+`subscribe` registers the single consumer; when `startingPosition` is `'LATEST'`, records buffered before the subscription are dropped. `record()` returns `{ seed, events }`. `replay(log, opts)` re-shards the log by `hash(pk)`, optionally shuffles and duplicates it (`ReplayOptions = { shuffle?: boolean; duplicate?: number }`), then re-sorts each shard into ascending `sequenceNumber` order before delivering — so cross-shard reordering and at-least-once chaos are modelled while the within-shard ordering guarantee that aggregation depends on is preserved.
+
+## Options
+
+```ts
+interface CdcEmulatorOptions {
+  models?: Function[];            // stream-enabled model classes (opt-in; default none)
+  mode?: CdcMode;                 // default 'inline'
+  clock?: ClockMode;              // default 'virtual' for queued, 'real' otherwise
+  batchSize?: number;             // default 100
+  maxRetries?: number;            // default 3
+  startingPosition?: 'TRIM_HORIZON' | 'LATEST'; // default 'TRIM_HORIZON'
+  seed?: number;                  // fault / shard determinism; default 1
+  shardCount?: number;            // default 8
+}
+```
+
+A `ModelStatic` (from `DDBModel.asModel()`) or a raw decorated class may be passed in `models`; a `ModelStatic` is unwrapped to its inner class so the stream opt-in and model-name filter align with the class the write paths key on.
+
+## Connecting to a consumer
+
+The emulator emits generic `ChangeEvent`s; wiring them to an aggregate is the consumer's job. A consumer subscribes, derives the work to do from each event, and reports per-record outcomes. Below, a consumer rebuilds a leaf-sum aggregate idempotently from `newImage`:
+
+```ts
+const cdc = createCdcEmulator({ models: [CounterModel], mode: 'queued', seed: 1 });
+
+const latestByLeaf = new Map<string, number>();
+cdc.subscribe(async (batch) => {
+  for (const e of batch.records) {
+    const key = `${e.keys.pk}|${e.keys.sk}`;
+    if (e.eventName === 'REMOVE') latestByLeaf.delete(key);
+    else latestByLeaf.set(key, Number((e.newImage as { value: number }).value));
+  }
+  // return { batchItemFailures: [...] } to redeliver specific records
+});
+
+await Counter.putItem({ siteId: 's1', leafId: 'a', value: 10 });
+await cdc.advanceClock(1); // drive delivery under the virtual clock
+```
+
+Sweep scheduling lives outside the emulator: the emulator handles only change production and delivery. In production, swap `createCdcEmulator` for a real Streams consumer; the consumer code is unchanged because the `ChangeEvent` type and delivery contract match.
+
+### Recording and replaying
+
+```ts
+const recorder = createCdcEmulator({ models: [CounterModel], mode: 'record', seed: 4 });
+await Counter.putItem({ siteId: 's1', leafId: 'a', value: 5 });
+await Counter.updateItem({ siteId: 's1', leafId: 'a' }, { value: 9 });
+const log = recorder.record();
+recorder.close();
+
+const replayer = createCdcEmulator({ mode: 'replay', seed: 4 });
+replayer.subscribe(/* idempotent, key-addressed consumer */);
+await replayer.replay(log, { shuffle: true, duplicate: 0.5 });
+```
+
+Because the consumer is idempotent and the replay preserves per-shard ordering, the final aggregate equals a full recompute from source regardless of the global delivery order or duplicates (replay equivalence).
+
+## Related
+
+- Pattern: [Aggregate Tree Pattern](../examples/aggregate-tree-pattern/README.md)