graphddb 0.4.3 → 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/cloudformation.md

@@ -0,0 +1,294 @@
+# GraphDDB — CloudFormation generation
+
+`graphddb generate cloudformation` emits an AWS CloudFormation template
+describing the **DynamoDB table(s)** a GraphDDB single-table design maps onto.
+GraphDDB is single-table by design: every entity that shares a `table` name
+contributes to the SAME `AWS::DynamoDB::Table`, and their Global Secondary
+Indexes are **unioned** by index name.
+
+The command consumes the same serializable manifest the Python bridge uses (it
+loads your entry model, builds the manifest from the shared metadata registry,
+and emits the template). Output is **deterministic** — the same model set always
+produces byte-identical output — and defaults to YAML (`--format json` for JSON).
+
+> This document describes the shipped `generate cloudformation` command. It is
+> the reference for the command's options, the resources it generates, the
+> derivation rules that map a model set onto a table, and its scope boundary.
+
+### Related specifications
+
+- [`spec.md`](./spec.md) — the core API: entities, structured keys / GSIs, the
+  physical key attributes (`PK` / `SK` / `<index>PK` / `<index>SK`).
+- [`design-patterns.md`](./design-patterns.md) — maintained access paths and the
+  `updateMode: 'stream'` signal that drives `--stream auto`.
+- [`python-bridge.md`](./python-bridge.md) — the other consumer of the same
+  manifest / SSoT.
+
+## Overview
+
+```bash
+graphddb generate cloudformation --entry models.ts --out table.yaml
+```
+
+- **`--entry`** loads the TypeScript (or pre-compiled `.js`/`.mjs`) module that
+  registers your entity models as a side effect of import. TypeScript modules are
+  transpiled on demand via `tsx` (an optional peer dependency — install it with
+  `npm i -D tsx`).
+- Without `--out`, the template is written verbatim to **stdout** (pipe-friendly).
+  With `--out`, it is written to that file and a JSON result
+  (`{"status":"ok","outDir":…,"files":[…]}`) is printed to stdout.
+
+## Options
+
+Every option below matches the shipped CLI contract (`cli-contract.yaml`) and the
+handler validation exactly.
+
+| Option | Alias | Type | Default | Notes / validation |
+|--------|-------|------|---------|--------------------|
+| `--entry` | `-e` | file | — (required) | Entry module that registers the entity models. Must exist / be readable; missing → exit `2`. |
+| `--out` | `-o` | file | stdout | Output file. Parent directories are created. Omitted → template to stdout. |
+| `--format` | `-f` | `yaml` \| `json` | `yaml` | Serialization format. Any other value → exit `2`. |
+| `--gsi-projection` | | `ALL` \| `KEYS_ONLY` | `ALL` | GSI `ProjectionType`. `ALL` projects every attribute; `KEYS_ONLY` projects only the key attributes. Other value → exit `2`. |
+| `--stream` | | `auto` \| `on` \| `off` | `auto` | DynamoDB Streams (`StreamSpecification` `NEW_AND_OLD_IMAGES`). `auto` emits a stream only when the model set uses stream-based maintenance (`updateMode: 'stream'`); `on` always emits; `off` never. When enabled, a `StreamArn` Output is added. Other value → exit `2`. |
+| `--billing-mode` | | `PAY_PER_REQUEST` \| `PROVISIONED` | `PAY_PER_REQUEST` | `PAY_PER_REQUEST` is on-demand (no provisioned throughput). `PROVISIONED` emits `BillingMode: PROVISIONED` with `ProvisionedThroughput` on the table **and every GSI**, and unlocks Auto Scaling. Other value → exit `2`. |
+| `--rcu` | | integer ≥ 1 | `5` | Provisioned `ReadCapacityUnits` on the table and every GSI. **Only valid with `--billing-mode PROVISIONED`** — supplying it with `PAY_PER_REQUEST` is a loud reject (exit `2`). Non-integer / `< 1` → exit `2`. |
+| `--wcu` | | integer ≥ 1 | `5` | Provisioned `WriteCapacityUnits`. Same rules as `--rcu`. |
+| `--autoscale` | | boolean flag | off | Enable Application Auto Scaling (a `ScalableTarget` + `ScalingPolicy` pair for the table read/write and each GSI read/write). **Only valid with `--billing-mode PROVISIONED`** — with `PAY_PER_REQUEST` it is a loud reject (exit `2`). |
+| `--autoscale-min` | | integer ≥ 1 | `5` | Auto Scaling `MinCapacity` for every scalable target. Must be `<= --autoscale-max` (else exit `2`). Meaningful only with `--autoscale`. |
+| `--autoscale-max` | | integer ≥ 1 | `100` | Auto Scaling `MaxCapacity` for every scalable target. Must be `>= --autoscale-min`. |
+| `--autoscale-target` | | integer 1–100 | `70` | Target utilization % (`TargetValue` of the target-tracking policy). `> 100` → exit `2`. |
+| `--pitr` | | boolean flag | off | Point-in-time recovery (`PointInTimeRecoverySpecification` `PointInTimeRecoveryEnabled: true`). Omitted entirely when off (never emitted as `false`). |
+| `--table-class` | | `STANDARD` \| `STANDARD_INFREQUENT_ACCESS` | omitted | Emits `TableClass: <value>`. Omitted by default (AWS defaults to `STANDARD`). Other value → exit `2`. |
+| `--sse` | | boolean flag | off | Server-side encryption with the AWS-owned/managed key (`SSESpecification` `SSEEnabled: true` — no KMS key ARN / SSEType). Omitted entirely when off. |
+
+### Exit codes
+
+- `0` — generation succeeded.
+- `1` — unexpected error (e.g. the entry module threw). JSON error on stderr.
+- `2` — invalid arguments (missing / unreadable `--entry`, an invalid enum value,
+  a bad integer, or a loud reject below). JSON error on stderr
+  (`{"code":"INVALID_ARGS","message":…}`).
+
+## Generated resources
+
+For each **physical table** the model set maps onto, the template emits:
+
+- **`AWS::DynamoDB::Table`** with:
+  - `TableName` — a `!Ref` to a `TableName` parameter whose default is the
+    physical table name. (Multi-table designs get one parameter per table, keyed
+    by logical id.)
+  - `BillingMode` — `PAY_PER_REQUEST` (default) or `PROVISIONED`.
+  - `AttributeDefinitions` — **key attributes only**, every one `AttributeType: S`
+    (see derivation rules).
+  - `KeySchema` — `PK` (HASH) plus `SK` (RANGE) when the base key has a sort key.
+  - `GlobalSecondaryIndexes` — one per unioned GSI (omitted when there are none).
+  - `ProvisionedThroughput` — on the table **and every GSI**, only under
+    `PROVISIONED`.
+  - `StreamSpecification` — `NEW_AND_OLD_IMAGES`, only when streams are enabled.
+  - `TimeToLiveSpecification` — only when a `@ttl` field is declared (see TTL).
+  - `PointInTimeRecoverySpecification` / `TableClass` / `SSESpecification` — only
+    when the corresponding `--pitr` / `--table-class` / `--sse` option is given.
+- **`AWS::ApplicationAutoScaling::ScalableTarget` + `::ScalingPolicy`** — separate
+  top-level resources (not table properties), only under `--autoscale`.
+- **Parameters** — a `TableName` (String, default = physical name).
+- **Outputs** — the table name (`Ref`) and ARN (`Fn::GetAtt … Arn`), plus a
+  `StreamArn` output when streams are enabled.
+
+All resources, attribute definitions, and GSIs are emitted in a stable (sorted)
+order, so the output is byte-deterministic.
+
+## Derivation rules
+
+How a GraphDDB model set is mapped onto the physical DynamoDB shape:
+
+1. **One physical table per logical `table` name.** Entities that share a `table`
+   are single-table siblings and contribute to the same `AWS::DynamoDB::Table`.
+   The CFn logical resource id is `<AlphanumericLogicalName>Table` (e.g.
+   `UserPermissions` → `UserPermissionsTable`).
+2. **Physical key attribute names match the runtime exactly.** The base partition
+   key is always `PK`; the base sort key (when present) is `SK`. Each GSI uses
+   `<indexName>PK` and `<indexName>SK` (e.g. `GSI1PK` / `GSI1SK`).
+3. **`AttributeDefinitions` are key attributes only, all `AttributeType: S`.** It
+   contains `PK`, `SK` (when the table has a sort key), and each GSI's `<index>PK`
+   plus `<index>SK` (only for GSIs that have a sort key). **Non-key attributes are
+   never added** — in particular the TTL attribute is deliberately kept out
+   (CloudFormation rejects a non-key attribute there; `TimeToLiveSpecification`
+   references it legitimately).
+4. **The base `KeySchema` is `PK` (HASH) + `SK` (RANGE).** `SK` is included when
+   **any** entity on the table declares a sort key; a PK-only design omits `SK`
+   and its attribute definition.
+5. **GSIs are unioned by index name across all entities on the table.** The same
+   `IndexName` declared by several entities collapses to one GSI. Each GSI's
+   `KeySchema` is `<index>PK` (HASH) plus `<index>SK` (RANGE) — HASH-only when the
+   GSI has no sort key. `Projection.ProjectionType` is `ALL` (default) or
+   `KEYS_ONLY`. (Full GSI-union consistency — same sort-key presence across
+   entities, ≤ 20 GSIs — is enforced statically at model registration by the
+   `cfn-schema-consistency` linter rule; the emitter keeps a backstop that throws
+   on a surviving inconsistency.)
+6. **Streams (`--stream auto`) are derived from maintenance metadata.** `auto`
+   emits a stream when any registered entity uses stream-based maintenance
+   (`updateMode: 'stream'` — on a relation `write`, a versioned relation preset,
+   an `@aggregate` `write`, or a view's `@maintainedFrom`). This signal comes from
+   the metadata registry, not the manifest. The single view type is
+   `NEW_AND_OLD_IMAGES` (stream-based maintenance needs both images).
+7. **TTL is derived from a `@ttl` field.** When an entity on the table declares a
+   `@ttl` field, its physical attribute name is carried in the manifest and
+   rendered as `TimeToLiveSpecification { AttributeName, Enabled: true }`. DynamoDB
+   allows exactly one TTL attribute per table; the manifest build enforces this,
+   and the emitter backstops it by throwing if two entities on a table disagree.
+8. **Provisioned throughput + Auto Scaling are pure deploy-time settings** (from
+   CLI options, not derived from the model). Under `PROVISIONED`, the table and
+   every GSI carry `ProvisionedThroughput` (`--rcu` / `--wcu`, default 5/5).
+   Under `--autoscale`, each of the table read/write and every GSI read/write gets
+   a `ScalableTarget` (`ServiceNamespace: dynamodb`, the matching
+   `ScalableDimension`, an `Fn::Sub` `ResourceId` tying to the table's `Ref`,
+   `MinCapacity`/`MaxCapacity`, and the DynamoDB service-linked role ARN) plus a
+   `TargetTrackingScaling` `ScalingPolicy` (predefined
+   `DynamoDBRead/WriteCapacityUtilization` metric, `TargetValue`). So **N GSIs →
+   `2×(1+N)` scalable targets + `2×(1+N)` scaling policies.** GSI targets
+   additionally `DependsOn` the table.
+9. **PITR / TableClass / SSE are pure deploy-time settings**, each defaulting to
+   OFF/omitted — the emitter omits the whole property rather than emitting a
+   `false`/default value.
+
+## Scope boundary
+
+This command generates **only the GraphDDB-managed DynamoDB resources** — the
+table(s), their GSIs, and the DynamoDB-adjacent settings above (Streams, TTL,
+PITR, TableClass, SSE, provisioned throughput, and the Application Auto Scaling
+resources for that table). It does **not** generate IAM roles/policies for your
+application, Lambda functions, API Gateway, stream consumers, DynamoDB Streams
+event-source mappings, or any other application infrastructure. The one IAM
+reference it emits is the AWS **service-linked** role ARN that Application Auto
+Scaling uses (built with `Fn::Sub` so `${AWS::AccountId}` resolves at deploy
+time) — it does not create an IAM role. Compose the generated template into your
+own stack (nested stack / module) alongside those app resources.
+
+## Loud-reject / validation behaviors
+
+The CLI validates arguments before generation and **rejects loudly** (exit `2`,
+JSON `INVALID_ARGS` on stderr) rather than silently ignoring a nonsensical
+combination. The pure emitter keeps the same guards as an authoritative backstop
+(it throws). The loud rejects are:
+
+- **`--rcu` / `--wcu` with `PAY_PER_REQUEST`** — on-demand tables have no
+  provisioned capacity, so accepting the value would mislead you.
+- **`--autoscale` with `PAY_PER_REQUEST`** — Application Auto Scaling on an
+  on-demand table is invalid in AWS.
+- **`--autoscale-min` > `--autoscale-max`** — an invalid scalable-target range.
+- **`--autoscale-target` > 100** — it is a utilization percentage (1–100).
+- **A non-integer or `< 1` value for `--rcu` / `--wcu` / `--autoscale-*`.**
+- **An invalid enum value** for `--format` / `--gsi-projection` / `--stream` /
+  `--billing-mode` / `--table-class`.
+- **A missing `--entry`** (or one that cannot be imported).
+
+Inconsistent single-table declarations (a GSI with conflicting sort-key presence,
+or two `@ttl` attributes on one table) are caught statically by the
+`cfn-schema-consistency` linter at model registration; the emitter throws as a
+backstop if one survives to generation time.
+
+## Worked example
+
+The [`user-permissions`](../examples/user-permissions/) example is a single
+`UserPermissions` table whose entities (users, groups, memberships, permissions)
+share one physical table, with a `GSI1` **unioned** across `UserModel` (email
+lookup) and `GroupMembershipModel` (the inverted membership index). It exercises
+the base `PK`/`SK` key and a GSI union — it does **not** use streams, TTL, PITR,
+provisioned throughput, or auto scaling (those are opt-in flags / a `@ttl`
+decorator this model does not trigger).
+
+Generate it (the committed sample
+[`examples/user-permissions/cloudformation.yaml`](../examples/user-permissions/cloudformation.yaml)
+is produced by exactly this command, and a drift-guard test keeps it in sync):
+
+```bash
+graphddb generate cloudformation \
+  --entry examples/user-permissions/models.ts \
+  --out examples/user-permissions/cloudformation.yaml
+```
+
+The generated template (default YAML):
+
+```yaml
+AWSTemplateFormatVersion: "2010-09-09"
+Description: DynamoDB table(s) for a GraphDDB single-table design (generated by graphddb generate cloudformation).
+Parameters:
+  TableName:
+    Type: String
+    Default: UserPermissions
+    Description: Name of the UserPermissions DynamoDB table.
+Resources:
+  UserPermissionsTable:
+    Type: "AWS::DynamoDB::Table"
+    Properties:
+      TableName:
+        Ref: TableName
+      BillingMode: PAY_PER_REQUEST
+      AttributeDefinitions:
+        - AttributeName: PK
+          AttributeType: S
+        - AttributeName: SK
+          AttributeType: S
+        - AttributeName: GSI1PK
+          AttributeType: S
+        - AttributeName: GSI1SK
+          AttributeType: S
+      KeySchema:
+        - AttributeName: PK
+          KeyType: HASH
+        - AttributeName: SK
+          KeyType: RANGE
+      GlobalSecondaryIndexes:
+        - IndexName: GSI1
+          KeySchema:
+            - AttributeName: GSI1PK
+              KeyType: HASH
+            - AttributeName: GSI1SK
+              KeyType: RANGE
+          Projection:
+            ProjectionType: ALL
+Outputs:
+  TableName:
+    Description: Name of the UserPermissions DynamoDB table.
+    Value:
+      Ref: UserPermissionsTable
+  TableArn:
+    Description: ARN of the UserPermissions DynamoDB table.
+    Value:
+      "Fn::GetAtt":
+        - UserPermissionsTable
+        - Arn
+```
+
+### More option combinations
+
+```bash
+# JSON output.
+graphddb generate cloudformation --entry models.ts --format json
+
+# Key-only GSI projection.
+graphddb generate cloudformation --entry models.ts --gsi-projection KEYS_ONLY --out table.yaml
+
+# Force a DynamoDB stream (NEW_AND_OLD_IMAGES) on.
+graphddb generate cloudformation --entry models.ts --stream on --out table.yaml
+
+# Deploy-time hardening: PITR + SSE + Infrequent-Access table class.
+graphddb generate cloudformation --entry models.ts --pitr --sse --table-class STANDARD_INFREQUENT_ACCESS --out table.yaml
+
+# Provisioned billing with fixed throughput.
+graphddb generate cloudformation --entry models.ts --billing-mode PROVISIONED --rcu 10 --wcu 5 --out table.yaml
+
+# Provisioned billing + Application Auto Scaling.
+graphddb generate cloudformation --entry models.ts \
+  --billing-mode PROVISIONED --autoscale --autoscale-min 5 --autoscale-max 100 --autoscale-target 70 --out table.yaml
+```
+
+## Validating the output
+
+Real `aws cloudformation validate-template` requires AWS credentials and the
+`cloudformation:ValidateTemplate` IAM permission. Where those are unavailable
+(this project's CI is IAM-blocked, for example), an equivalent **structural**
+check is enough for a syntax gate: generate the template in both formats, parse
+each (YAML + JSON), assert the two agree, and assert the table structure. The
+repository wires this as `npm run validate:cfn` (see `scripts/validate-cfn.mjs`),
+which the CI runs as its "Validate generated CloudFormation (structural)" step.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphddb",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "description": "Graph data modeling on DynamoDB with adjacency list pattern",
   "type": "module",
   "main": "dist/index.js",
@@ -37,6 +37,7 @@
     "test:py": "python3 -m pytest python/tests -m \"not integration\"",
     "test:py:integration": "python3 -m pytest python/tests -m integration",
     "test:conformance": "tsx conformance/run.ts",
+    "validate:cfn": "node scripts/validate-cfn.mjs",
     "gen:cli": "cli-contracts generate",
     "gen:cli:check": "cli-contracts generate --dry-run",
     "clean": "rm -rf dist",
@@ -70,7 +71,8 @@
     "tsup": "^8.0.0",
     "tsx": "^4.22.4",
     "typescript": "^5.5.0",
-    "vitest": "^3.0.0"
+    "vitest": "^3.0.0",
+    "yaml": "^2.9.0"
   },
   "engines": {
     "node": ">=22"