graphddb 0.5.3 → 0.7.0

package/dist/index.d.ts

@@ -1,11 +1,11 @@
-export { a as LintResult, L as LintRule, b as Linter, M as MetadataRegistry } from './registry-BD_5Rm5C.js';
-import { aN as SelectableOf, aO as PrimaryKeyOf, aP as RequestContext, aQ as Middleware, aR as ReadRequestKind, aS as CtxModel, aT as ReadParams, aU as ReadRequestCtx, D as DynamoDBOperation, aV as Item, n as Executor, aW as RetryPolicy, am as ExecutionPlanSpec, aX as KeyDefinition, aY as GsiDefinition, aZ as ModelKind, a_ as FieldOptions, a$ as DynamoType, b0 as ProjectionTransform, b1 as MaintainEvent, b2 as MembershipPredicate, b3 as MaintainConsistency, b4 as MaintainUpdateMode, b5 as MembershipPredicateOp, b6 as RelationOptions, b7 as AggregateOptions, b8 as AggregateValue, b9 as SelectBuilderSpec, ba as RawCondition, m as EntityMetadata, N as TransactionSpec, _ as Manifest, bb as RetryOverride, bc as ExecutionPlan, bd as FieldMetadata, be as ResolvedKey, o as ReadExecOptions, p as ExecutorResult, q as BatchGetExecInput, P as PutInput, W as WriteExecOptions, r as WriteResult, s as UpdateInput, t as DeleteInput, u as BatchWriteExecItem, v as BatchExecOptions, T as TransactWriteExecItem, bf as RelationMetadata, aC as TransactionItemSpec, bg as MaintainEffect, M as ModelStatic, w as DDBModel, V as ViewDefinition, A as Param, x as ParamDescriptor, X as DefinitionMap, bh as OperationDefinition, bi as WriteDefinitionOptions, bj as PartialQueryKeyOf, bk as StrictSelectSpec, bl as ReadDefinitionOptions, bm as EntityInput, bn as UniqueQueryKeyOf } from './maintenance-view-adapter-D5t9taTE.js';
-export { bo as AggregateMetadata, Z as AnyOperationDefinition, bp as BatchDeleteRequest, bq as BatchGetOptions, br as BatchGetRequest, bs as BatchGetResult, bt as BatchPutRequest, B as BatchResult, bu as BatchWriteRequest, $ as BridgeBundle, bv as CONTRACT_RANGE_FANOUT_CONCURRENCY, C as CdcEmulatorOptions, a as CdcMode, bw as CdcModelRegistry, bx as CdcSubscribeHandlers, by as Change, b as ChangeBatch, c as ChangeEvent, d as ChangeEventName, e as ChangeHandler, f as ClockMode, bz as CollectionEffect, bA as CollectionOptions, bB as Column, bC as ColumnMap, a1 as CommandContractMethodSpec, bD as CommandInputShape, bE as CommandMethod, I as CommandMethodSpec, H as CommandModelContract, bF as CommandPlan, a2 as CommandResolutionTarget, bG as CommandResultKind, bH as CommandSelectShape, L as CommandSpec, a3 as CompiledFragment, a5 as ComposeSpec, g as ConcurrentRecomputeRef, bI as CondSlot, bJ as ConditionCheckInput, z as ConditionInput, a0 as ConditionSpec, bK as Connection, O as ContextSpec, bL as ContractCallSignature, a7 as ContractCardinality, bM as ContractCommandParams, a8 as ContractCommandResult, bN as ContractComposeNode, bO as ContractFromRef, a9 as ContractInputArity, bP as ContractItem, bQ as ContractKeyFieldRef, bR as ContractKeyInput, bS as ContractKeyRef, aa as ContractKeySpec, ab as ContractKind, bT as ContractMethodOp, bU as ContractParamRef, bV as ContractQueryParams, ac as ContractResolution, J as ContractSpec, bW as CounterAggregate, bX as CounterEffect, bY as CtxBase, bZ as DEFAULT_MAX_ATTEMPTS, b_ as DEFAULT_RETRY_POLICY, b$ as DeleteOptions, c0 as DeriveEffect, ae as DerivedEdgeWrite, ak as DerivedUpdate, c1 as DescriptorBinding, c2 as ENTITY_WRITES_MARKER, c3 as EdgeEffect, c4 as EffectPath, c5 as EmbeddedMetadata, c6 as EmitEffect, y as EntityRef, c7 as EntityWritesDefinition, c8 as EntityWritesShape, E as EventLog, c9 as ExecutableCommandContract, ca as ExecutableQueryContract, F as FaultSpec, cb as FilterInput, an as FilterSpec, cc as FragmentInput, cd as GsiDefinitionMarker, ce as GsiOptions, cf as IdempotencyEffect, cg as InProcessWriteDescriptor, ch as InputArity, ci as KeyDefinitionMarker, cj as KeySegment, ck as KeySlot, cl as KeyStructure, cm as KeyedResult, cn as LIFECYCLE_CONTRACT_MARKER, co as LifecycleContract, cp as LifecycleEffects, cq as LiteralParam, cr as MaintainItem, cs as MaintainTrigger, ct as MaintenanceGraph, ap as ManifestEntity, aq as ManifestField, ar as ManifestFieldType, as as ManifestGsi, at as ManifestKey, au as ManifestRelation, av as ManifestTable, cu as MembershipEffect, cv as ModelRef, cw as MutateMode, cx as MutateOptions, cy as MutateParallelResult, cz as MutateTransactionResult, cA as MutationBody, cB as MutationDescriptorMap, cC as MutationFragment, cD as MutationInputProxy, cE as MutationInputRef, cF as MutationIntent, cG as NumberParam, cH as OperationKind, aw as OperationSpec, Y as OperationsDocument, cI as ParallelOpResult, cJ as ParamKind, ax as ParamSpec, cK as ParamStructure, cL as PersistCtx, cM as PersistOrigin, cN as PlannedCommandMethod, cO as ProjectionMap, cP as ProjectionTransformOp, cQ as PutOptions, ay as QueryContractMethodSpec, cR as QueryEnvelopeResult, cS as QueryKeyOf, cT as QueryMethod, G as QueryMethodSpec, Q as QueryModelContract, cU as QueryResult, K as QuerySpec, az as RangeConditionSpec, cV as ReadEnvelope, cW as ReadOpCtx, cX as ReadOpKind, aA as ReadOperationType, cY as ReadRouteDescriptor, cZ as ReadRouteOptions, c_ as ReadRouteResult, c$ as RecordedCompose, d0 as RelationBuilder, d1 as RelationConsistency, d2 as RelationLimitOptions, d3 as RelationPattern, d4 as RelationProjection, d5 as RelationReadOptions, d6 as RelationSelect, d7 as RelationSpec, d8 as RelationUpdateMode, d9 as RelationWriteOptions, R as ReplayOptions, da as RequiresEffect, db as Resolution, dc as RetryInfo, dd as RetryOperationKind, aB as SPEC_VERSION, de as SegmentSpec, df as SegmentedKey, dg as SelectBuilder, dh as SelectOf, S as ShardId, di as SnapshotEffect, h as StartingPosition, i as StreamViewType, dj as StringParam, j as SubscribeHandler, k as SubscribeHandlers, dk as TransactionContext, aD as TransactionItemType, dl as UniqueEffect, dm as Updatable, dn as UpdateOptions, dp as ViewSourceSlice, aE as WhenSpec, dq as WriteCtx, dr as WriteDescriptor, ds as WriteEnvelope, dt as WriteInput, du as WriteKind, dv as WriteLifecyclePhase, dw as WriteMiddleware, aF as WriteOperationType, dx as WriteRecorder, dy as WriteResultProjection, dz as attachModelClass, dA as buildDeleteInput, dB as buildMaintenanceGraph, dC as buildPutInput, l as buildSubscribeHandler, dD as buildUpdateInput, dE as collectViewDefinitions, aH as compileFragment, aI as compileMutationPlan, aJ as compileSingleFragmentPlan, dF as cond, dG as contractOfMethodSpec, dH as definePlan, dI as entityWrites, dJ as executeBatchGet, dK as executeBatchWrite, dL as executeCommandMethod, dM as executeDelete, dN as executeKeyedBatchGet, dO as executePut, dP as executeQueryMethod, dQ as executeRangeFanout, dR as executeTransaction, dS as executeUpdate, dT as from, dU as getEntityWrites, dV as gsi, dW as identity, dX as isColumn, dY as isCommandModelContract, dZ as isCommandPlan, d_ as isContractComposeNode, d$ as isContractFromRef, e0 as isContractKeyFieldRef, e1 as isContractKeyRef, e2 as isContractParamRef, e3 as isEntityWritesDefinition, e4 as isKeySegment, e5 as isLifecycleContract, e6 as isMaintainTrigger, e7 as isMutationFragment, e8 as isMutationInputRef, e9 as isParam, ea as isPlannedCommandMethod, eb as isQueryModelContract, ec as isRetryableError, ed as isRetryableTransactionCancellation, ee as k, ef as key, eg as lifecyclePhaseForIntent, eh as maintainTrigger, ei as mintContractKeyFieldRef, ej as mintContractParamRef, ek as mutation, el as param, em as preview, en as publicCommandModel, eo as publicQueryModel, ep as query, aL as resolveLifecycle, eq as wholeKeysSentinel } from './maintenance-view-adapter-D5t9taTE.js';
+export { a as LintResult, L as LintRule, b as Linter, M as MetadataRegistry } from './registry-Cv9nl_3i.js';
+import { aN as SelectableOf, aO as PrimaryKeyOf, aP as RequestContext, aQ as Middleware, aR as ReadRequestKind, aS as CtxModel, aT as ReadParams, aU as ReadRequestCtx, D as DynamoDBOperation, aV as Item, n as Executor, aW as RetryPolicy, am as ExecutionPlanSpec, aX as KeyDefinition, aY as GsiDefinition, aZ as ModelKind, a_ as FieldOptions, a$ as DynamoType, b0 as ProjectionTransform, b1 as MaintainEvent, b2 as MembershipPredicate, b3 as MaintainConsistency, b4 as MaintainUpdateMode, b5 as MembershipPredicateOp, b6 as RelationOptions, b7 as AggregateOptions, b8 as AggregateValue, b9 as SelectBuilderSpec, ba as RawCondition, m as EntityMetadata, N as TransactionSpec, _ as Manifest, bb as RetryOverride, bc as ExecutionPlan, bd as FieldMetadata, be as ResolvedKey, o as ReadExecOptions, p as ExecutorResult, q as BatchGetExecInput, P as PutInput, W as WriteExecOptions, r as WriteResult, s as UpdateInput, t as DeleteInput, u as BatchWriteExecItem, v as BatchExecOptions, T as TransactWriteExecItem, bf as RelationMetadata, aC as TransactionItemSpec, bg as MaintainEffect, M as ModelStatic, w as DDBModel, V as ViewDefinition, A as Param, x as ParamDescriptor, X as DefinitionMap, bh as OperationDefinition, bi as WriteDefinitionOptions, bj as PartialQueryKeyOf, bk as StrictSelectSpec, bl as ReadDefinitionOptions, bm as EntityInput, bn as UniqueQueryKeyOf } from './maintenance-view-adapter-BP2CJDdz.js';
+export { bo as AggregateMetadata, Z as AnyOperationDefinition, bp as BatchDeleteRequest, bq as BatchGetOptions, br as BatchGetRequest, bs as BatchGetResult, bt as BatchPutRequest, B as BatchResult, bu as BatchWriteRequest, $ as BridgeBundle, bv as CONTRACT_RANGE_FANOUT_CONCURRENCY, C as CdcEmulatorOptions, a as CdcMode, bw as CdcModelRegistry, bx as CdcSubscribeHandlers, by as Change, b as ChangeBatch, c as ChangeEvent, d as ChangeEventName, e as ChangeHandler, f as ClockMode, bz as CollectionEffect, bA as CollectionOptions, bB as Column, bC as ColumnMap, a1 as CommandContractMethodSpec, bD as CommandInputShape, bE as CommandMethod, I as CommandMethodSpec, H as CommandModelContract, bF as CommandPlan, a2 as CommandResolutionTarget, bG as CommandResultKind, bH as CommandSelectShape, L as CommandSpec, a3 as CompiledFragment, a5 as ComposeSpec, g as ConcurrentRecomputeRef, bI as CondSlot, bJ as ConditionCheckInput, z as ConditionInput, a0 as ConditionSpec, bK as Connection, O as ContextSpec, bL as ContractCallSignature, a7 as ContractCardinality, bM as ContractCommandParams, a8 as ContractCommandResult, bN as ContractComposeNode, bO as ContractFromRef, a9 as ContractInputArity, bP as ContractItem, bQ as ContractKeyFieldRef, bR as ContractKeyInput, bS as ContractKeyRef, aa as ContractKeySpec, ab as ContractKind, bT as ContractMethodOp, bU as ContractParamRef, bV as ContractQueryParams, ac as ContractResolution, J as ContractSpec, bW as CounterAggregate, bX as CounterEffect, bY as CtxBase, bZ as DEFAULT_MAX_ATTEMPTS, b_ as DEFAULT_RETRY_POLICY, b$ as DeleteOptions, c0 as DeriveEffect, ae as DerivedEdgeWrite, ak as DerivedUpdate, c1 as DescriptorBinding, c2 as ENTITY_WRITES_MARKER, c3 as EdgeEffect, c4 as EffectPath, c5 as EmbeddedMetadata, c6 as EmitEffect, y as EntityRef, c7 as EntityWritesDefinition, c8 as EntityWritesShape, E as EventLog, c9 as ExecutableCommandContract, ca as ExecutableQueryContract, F as FaultSpec, cb as FilterInput, an as FilterSpec, cc as FragmentInput, cd as GsiDefinitionMarker, ce as GsiOptions, cf as IdempotencyEffect, cg as InProcessWriteDescriptor, ch as InlineSnapshotSpec, ci as InputArity, cj as KeyDefinitionMarker, ck as KeySegment, cl as KeySlot, cm as KeyStructure, cn as KeyedResult, co as LIFECYCLE_CONTRACT_MARKER, cp as LifecycleContract, cq as LifecycleEffects, cr as LiteralParam, cs as MaintainItem, ct as MaintainTrigger, cu as MaintenanceGraph, ap as ManifestEntity, aq as ManifestField, ar as ManifestFieldType, as as ManifestGsi, at as ManifestKey, au as ManifestRelation, av as ManifestTable, cv as MembershipEffect, cw as ModelRef, cx as MutateMode, cy as MutateOptions, cz as MutateParallelResult, cA as MutateTransactionResult, cB as MutationBody, cC as MutationDescriptorMap, cD as MutationFragment, cE as MutationInputProxy, cF as MutationInputRef, cG as MutationIntent, cH as NumberParam, cI as OperationKind, aw as OperationSpec, Y as OperationsDocument, cJ as PREPARE_CACHE_MAX, cK as ParallelOpResult, cL as ParamKind, ax as ParamSpec, cM as ParamStructure, cN as PersistCtx, cO as PersistOrigin, cP as PlannedCommandMethod, cQ as PreparedBody, cR as PreparedInputProxy, cS as PreparedParamRef, cT as PreparedReadExecOptions, cU as PreparedReadRoute, cV as PreparedReadStatement, cW as PreparedStatement, cX as PreparedWriteExecOptions, cY as PreparedWriteRoute, cZ as PreparedWriteStatement, c_ as ProjectionMap, c$ as ProjectionTransformOp, d0 as PutOptions, ay as QueryContractMethodSpec, d1 as QueryEnvelopeResult, d2 as QueryKeyOf, d3 as QueryMethod, G as QueryMethodSpec, Q as QueryModelContract, d4 as QueryResult, K as QuerySpec, az as RangeConditionSpec, d5 as ReadEnvelope, d6 as ReadOpCtx, d7 as ReadOpKind, aA as ReadOperationType, d8 as ReadRouteDescriptor, d9 as ReadRouteOptions, da as ReadRouteResult, db as RecordedCompose, dc as RelationBuilder, dd as RelationConsistency, de as RelationLimitOptions, df as RelationPattern, dg as RelationProjection, dh as RelationReadOptions, di as RelationSelect, dj as RelationSpec, dk as RelationUpdateMode, dl as RelationWriteOptions, R as ReplayOptions, dm as RequiresEffect, dn as Resolution, dp as RetryInfo, dq as RetryOperationKind, aB as SPEC_VERSION, dr as SegmentSpec, ds as SegmentedKey, dt as SelectBuilder, du as SelectOf, S as ShardId, dv as SnapshotEffect, h as StartingPosition, i as StreamViewType, dw as StringParam, j as SubscribeHandler, k as SubscribeHandlers, dx as TransactionContext, aD as TransactionItemType, dy as UniqueEffect, dz as Updatable, dA as UpdateOptions, dB as ViewSourceSlice, aE as WhenSpec, dC as WriteCtx, dD as WriteDescriptor, dE as WriteEnvelope, dF as WriteInput, dG as WriteKind, dH as WriteLifecyclePhase, dI as WriteMiddleware, aF as WriteOperationType, dJ as WriteRecorder, dK as WriteResultProjection, dL as attachModelClass, dM as buildDeleteInput, dN as buildMaintenanceGraph, dO as buildPutInput, l as buildSubscribeHandler, dP as buildUpdateInput, dQ as collectViewDefinitions, aH as compileFragment, aI as compileMutationPlan, aJ as compileSingleFragmentPlan, dR as cond, dS as contractOfMethodSpec, dT as definePlan, dU as entityWrites, dV as executeBatchGet, dW as executeBatchWrite, dX as executeCommandMethod, dY as executeDelete, dZ as executeKeyedBatchGet, d_ as executePut, d$ as executeQueryMethod, e0 as executeRangeFanout, e1 as executeTransaction, e2 as executeUpdate, e3 as from, e4 as getEntityWrites, e5 as gsi, e6 as identity, e7 as isColumn, e8 as isCommandModelContract, e9 as isCommandPlan, ea as isContractComposeNode, eb as isContractFromRef, ec as isContractKeyFieldRef, ed as isContractKeyRef, ee as isContractParamRef, ef as isEntityWritesDefinition, eg as isKeySegment, eh as isLifecycleContract, ei as isMaintainTrigger, ej as isMutationFragment, ek as isMutationInputRef, el as isParam, em as isPlannedCommandMethod, en as isPreparedParamRef, eo as isQueryModelContract, ep as isRetryableError, eq as isRetryableTransactionCancellation, er as k, es as key, et as lifecyclePhaseForIntent, eu as maintainTrigger, ev as mintContractKeyFieldRef, ew as mintContractParamRef, ex as mutation, ey as param, ez as prepare, eA as preview, eB as publicCommandModel, eC as publicQueryModel, eD as query, aL as resolveLifecycle, eE as wholeKeysSentinel } from './maintenance-view-adapter-BP2CJDdz.js';
 import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
 import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
-export { C as CdcEmulator, M as MAINT_OUTBOX_PK_PREFIX, a as MaintenanceDrain, b as MaintenanceDrainOptions, c as createCdcEmulator, d as createMaintenanceDrain, e as createMaintenanceDrainHandler, p as parseChange } from './from-change-DQK2Jm9R.js';
-export { c as createDefaultLinter, g as gsiAmbiguityRule, m as missingGsiRule, n as noScanRule, q as queryBoundaryRule, r as relationDepthRule, a as requireLimitRule } from './relation-depth-DLkhG0xX.js';
-export { A as AnyModelContract, B as BuiltContracts, C as ContextOwnership, a as ContextOwnershipMap, b as ContractBoundaryViolation, c as ContractInputs, d as ContractMap, e as ContractN1Violation, T as TransactionDefinition, f as TransactionParamShape, g as TransactionRef, h as TxConditionCheckOptions, i as TxForEachInstruction, j as TxForEachOptions, k as TxInstruction, l as TxRecorder, m as TxWriteInstruction, n as TxWriteOptions, W as WhenComparison, o as assertBundleSerializable, p as assertContractBoundaries, q as assertContractN1Safe, r as assertJsonSerializable, s as assertSupportedCondition, t as buildBridgeBundle, u as buildContexts, v as buildContracts, w as buildManifest, x as buildOperations, y as buildQuerySpec, z as buildTransactionSpec, D as buildTransactions, E as collectContractBoundaryViolations, F as collectContractN1Violations, G as defineTransaction, H as defineTransactions, I as isTransactionRef, J as when } from './index-CtDBo8Se.js';
+export { C as CdcEmulator, M as MAINT_OUTBOX_PK_PREFIX, a as MaintenanceDrain, b as MaintenanceDrainOptions, c as createCdcEmulator, d as createMaintenanceDrain, e as createMaintenanceDrainHandler, p as parseChange } from './from-change-pnURY-cV.js';
+export { c as createDefaultLinter, g as gsiAmbiguityRule, m as missingGsiRule, n as noScanRule, q as queryBoundaryRule, r as relationDepthRule, a as requireLimitRule } from './relation-depth-BR0y7Q1i.js';
+export { A as AnyModelContract, B as BuiltContracts, C as ContextOwnership, a as ContextOwnershipMap, b as ContractBoundaryViolation, c as ContractInputs, d as ContractMap, e as ContractN1Violation, T as TransactionDefinition, f as TransactionParamShape, g as TransactionRef, h as TxConditionCheckOptions, i as TxForEachInstruction, j as TxForEachOptions, k as TxInstruction, l as TxRecorder, m as TxWriteInstruction, n as TxWriteOptions, W as WhenComparison, o as assertBundleSerializable, p as assertContractBoundaries, q as assertContractN1Safe, r as assertJsonSerializable, s as assertSupportedCondition, t as buildBridgeBundle, u as buildContexts, v as buildContracts, w as buildManifest, x as buildOperations, y as buildQuerySpec, z as buildTransactionSpec, D as buildTransactions, E as collectContractBoundaryViolations, F as collectContractN1Violations, G as defineTransaction, H as defineTransactions, I as isTransactionRef, J as when } from './index-Eg94ChE1.js';
 
 /**
  * Query options with conditional `consistentRead` availability.
@@ -784,6 +784,48 @@ type HasManyVersionedCallback<Self, Source> = (self: SelfProxy<Self>, source: So
 
 declare function hasMany(targetFactory: () => new (...args: unknown[]) => unknown, keyBinding: Record<string, string>, options?: RelationOptions): (value: undefined, context: ClassFieldDecoratorContext) => void;
 declare function hasMany<Self = unknown, Source = unknown>(targetFactory: () => new (...args: unknown[]) => unknown, callback: HasManyVersionedCallback<Self, Source>): (value: undefined, context: ClassFieldDecoratorContext) => void;
+/**
+ * Options for a `@refs` relation (issue #197, Pattern 2 Embedded Refs read side).
+ *
+ * A `@refs` relation resolves an **inline id-list** on the parent row into the
+ * referenced child bodies in ONE deduped `BatchGetItem`:
+ *
+ * ```ts
+ * @list tagRefs!: { tagId: string }[];            // the stored inline ref list
+ * @refs(() => PTagModel, { from: 'tagRefs', key: 'tagId' })
+ * tags!: PTagModel[];                              // resolved child bodies
+ * ```
+ *
+ * `Model.query(key, { tags: { select: { name: true } } })` then reads the parent,
+ * pulls `tagId` off each `tagRefs` element, dedupes, and hydrates the `PTag`
+ * bodies in a single BatchGet — the exact physical cost (parent read + 1
+ * BatchGet) of the manual two-call form, but declarative and typed.
+ */
+interface RefsOptions extends RelationOptions {
+    /** The parent LIST attribute holding the inline reference elements (e.g. `'tagRefs'`). */
+    from: string;
+    /** The key field to read off EACH list element (e.g. `'tagId'`). */
+    key: string;
+    /**
+     * The TARGET child key field the element key binds to. Defaults to `key` (the
+     * common case where the element field name matches the child's key field name,
+     * e.g. `tagRefs[].tagId` → `PTag.tagId`). Supply when they differ.
+     */
+    to?: string;
+}
+/**
+ * Declares a **`refs`** relation (issue #197): the parent row holds an inline
+ * id-list (`from`, a `@list` attribute) whose elements each carry a reference key
+ * (`key`); the relation resolves those references to the target child bodies in a
+ * single deduped `BatchGetItem` at read time
+ * (`Model.query(key, { <prop>: { select: {…} } })`).
+ *
+ * The decorated property must be declared as an array of the target model
+ * (`tags!: PTagModel[]`), so it selects/returns like a bounded collection
+ * (`{ items, cursor }`, `cursor` always `null` — a refs list is finite, not
+ * paged).
+ */
+declare function refs(targetFactory: () => new (...args: unknown[]) => unknown, options: RefsOptions): (_value: undefined, context: ClassFieldDecoratorContext) => void;
 declare function belongsTo(targetFactory: () => new (...args: unknown[]) => unknown, keyBinding: Record<string, string>, options?: RelationOptions): (_value: undefined, context: ClassFieldDecoratorContext) => void;
 declare function hasOne(targetFactory: () => new (...args: unknown[]) => unknown, keyBinding: Record<string, string>, options?: RelationOptions): (value: undefined, context: ClassFieldDecoratorContext) => void;
 declare function hasOne<Self = unknown, Source = unknown>(targetFactory: () => new (...args: unknown[]) => unknown, callback: HasOneVersionedCallback<Self, Source>): (value: undefined, context: ClassFieldDecoratorContext) => void;
@@ -1149,7 +1191,10 @@ interface ProjectionResult {
  *
  * Rules:
  * - scalar (`true`) → field name added to projection
- * - embedded (object without `select` property) → nested path e.g. `#p0.#p1`
+ * - inline embeddedSnapshot read (`{ inline: true }`, issue #196) → the owner-row
+ *   physical attribute is added to the projection like a scalar (the maintained
+ *   copy is read straight off the row, NOT traversed to child partitions)
+ * - embedded (object without `select`/`inline`) → nested path e.g. `#p0.#p1`
  * - relation (object with `select` property) → excluded from projection
  * - additionalFields → added to projection (for implicit key resolution)
  */
@@ -2055,4 +2100,4 @@ type WriteOnlyDefinitions<D extends DefinitionMap> = {
     [K in keyof D]: D[K] extends OperationDefinition<infer _T, infer Op, infer _K, infer _S, infer _Ch, infer _P> ? Op extends 'put' | 'update' | 'delete' ? D[K] : OperationDefinition<DDBModel, 'put' | 'update' | 'delete', unknown, unknown, unknown, Record<string, ParamDescriptor>> : never;
 };
 
-export { AggregateOptions, AggregateValue, BATCH_GET_MAX_KEYS, BATCH_WRITE_MAX_ITEMS, BatchExecOptions, BatchGetExecInput, BatchWriteExecItem, ClientManager, type CollectParams, type ConditionExpressionResult, CtxModel, DDBModel, DefinitionMap, DeleteInput, type DriftReport, DynamoDBOperation, DynamoExecutor, DynamoType, EDGE_WRITES_MARKER, type EdgeLifecycle, type EdgeWriteDeclaration, type EdgeWriteRecorder, type EdgeWritesDefinition, EntityMetadata, ExecutionPlan, Executor, ExecutorResult, type ExplainInput, FieldMetadata, FieldOptions, type FilterExpressionResult, GsiDefinition, type HasManyVersionedCallback, type HasManyVersionedOptions, type HasOneVersionedCallback, type HasOneVersionedOptions, Item, KeyDefinition, type ListInput, type ListOptions, MAX_TRANSACT_ITEMS, MaintainConsistency, MaintainEffect, MaintainEvent, MaintainUpdateMode, type MaintainedFromCallback, type MaintainedFromOptions, type MaintenanceRebuildOptions, MaintenanceRebuilder, Manifest, MembershipPredicate, MembershipPredicateOp, Middleware, type ModelOptions, ModelStatic, OLD_VALUE_NAMESPACE, OperationDefinition, Param, ParamDescriptor, type Parameterize, PartialQueryKeyOf, type PerKeyCursorEnvelope, type PlanInput, PrimaryKeyOf, type ProjectionResult, ProjectionTransform, type ProjectionValue, PutInput, type QueryOptions$1 as QueryOptions, RawCondition, ReadExecOptions, ReadParams, ReadRequestCtx, ReadRequestKind, type RebuildResult, RelationMetadata, RelationOptions, type RelationTraversalOptions, RequestContext, ResolvedKey, RetryOverride, RetryPolicy, RetryingExecutor, SelectableOf, type SelfProxy, type SelfRef, type SourceProxy, type SourceRef, TableMapping, TransactWriteExecItem, TransactionItemSpec, TransactionSpec, UniqueQueryKeyOf, type UpdateExpressionResult, UpdateInput, type VersionedHistoryOptions, type VersionedLatestOptions, ViewDefinition, WriteDefinitionOptions, WriteExecOptions, WriteResult, aggregate, belongsTo, binary, boolean, buildConditionExpression, buildProjection, buildUpdateExpression, cdcProjected, compileFilterExpression, count, createMaintenanceRebuilder, datetime, decodeCursor, decodePerKeyCursor, defineCommands, defineDelete, defineList, definePut, defineQueries, defineQuery, defineUpdate, deriveEdgeWriteItems, deriveEdgeWriteItemsFor, deriveModelEdgeWriteItems, derivePrefix, detectRelationFields, edgeWrites, embedded, encodeCursor, encodePerKeyCursor, evaluateFilter, execute, executeDeclarativeTransaction, executeExplain, executeList, executeQuery, expandTransaction, field, getEdgeWrites, getImplicitKeyFields, hasMany, hasOne, hydrate, isEdgeWritesDefinition, isSelectBuilder, list, literal, maintainedFrom, map, max, model, number, numberSet, plan, resolveKey, resolveRelations, serializeContractKey, serializeFieldValue, string, stringSet, ttl, validateDepth, validateGsiAmbiguity, whenMember };
+export { AggregateOptions, AggregateValue, BATCH_GET_MAX_KEYS, BATCH_WRITE_MAX_ITEMS, BatchExecOptions, BatchGetExecInput, BatchWriteExecItem, ClientManager, type CollectParams, type ConditionExpressionResult, CtxModel, DDBModel, DefinitionMap, DeleteInput, type DriftReport, DynamoDBOperation, DynamoExecutor, DynamoType, EDGE_WRITES_MARKER, type EdgeLifecycle, type EdgeWriteDeclaration, type EdgeWriteRecorder, type EdgeWritesDefinition, EntityMetadata, ExecutionPlan, Executor, ExecutorResult, type ExplainInput, FieldMetadata, FieldOptions, type FilterExpressionResult, GsiDefinition, type HasManyVersionedCallback, type HasManyVersionedOptions, type HasOneVersionedCallback, type HasOneVersionedOptions, Item, KeyDefinition, type ListInput, type ListOptions, MAX_TRANSACT_ITEMS, MaintainConsistency, MaintainEffect, MaintainEvent, MaintainUpdateMode, type MaintainedFromCallback, type MaintainedFromOptions, type MaintenanceRebuildOptions, MaintenanceRebuilder, Manifest, MembershipPredicate, MembershipPredicateOp, Middleware, type ModelOptions, ModelStatic, OLD_VALUE_NAMESPACE, OperationDefinition, Param, ParamDescriptor, type Parameterize, PartialQueryKeyOf, type PerKeyCursorEnvelope, type PlanInput, PrimaryKeyOf, type ProjectionResult, ProjectionTransform, type ProjectionValue, PutInput, type QueryOptions$1 as QueryOptions, RawCondition, ReadExecOptions, ReadParams, ReadRequestCtx, ReadRequestKind, type RebuildResult, type RefsOptions, RelationMetadata, RelationOptions, type RelationTraversalOptions, RequestContext, ResolvedKey, RetryOverride, RetryPolicy, RetryingExecutor, SelectableOf, type SelfProxy, type SelfRef, type SourceProxy, type SourceRef, TableMapping, TransactWriteExecItem, TransactionItemSpec, TransactionSpec, UniqueQueryKeyOf, type UpdateExpressionResult, UpdateInput, type VersionedHistoryOptions, type VersionedLatestOptions, ViewDefinition, WriteDefinitionOptions, WriteExecOptions, WriteResult, aggregate, belongsTo, binary, boolean, buildConditionExpression, buildProjection, buildUpdateExpression, cdcProjected, compileFilterExpression, count, createMaintenanceRebuilder, datetime, decodeCursor, decodePerKeyCursor, defineCommands, defineDelete, defineList, definePut, defineQueries, defineQuery, defineUpdate, deriveEdgeWriteItems, deriveEdgeWriteItemsFor, deriveModelEdgeWriteItems, derivePrefix, detectRelationFields, edgeWrites, embedded, encodeCursor, encodePerKeyCursor, evaluateFilter, execute, executeDeclarativeTransaction, executeExplain, executeList, executeQuery, expandTransaction, field, getEdgeWrites, getImplicitKeyFields, hasMany, hasOne, hydrate, isEdgeWritesDefinition, isSelectBuilder, list, literal, maintainedFrom, map, max, model, number, numberSet, plan, refs, resolveKey, resolveRelations, serializeContractKey, serializeFieldValue, string, stringSet, ttl, validateDepth, validateGsiAmbiguity, whenMember };

package/dist/index.js

@@ -7,6 +7,9 @@ import {
   EDGE_WRITES_MARKER,
   MARKER_ROW_ENTITY,
   OLD_VALUE_NAMESPACE,
+  PREPARE_CACHE_MAX,
+  PreparedReadStatement,
+  PreparedWriteStatement,
   RELATION_TRAVERSAL_CONCURRENCY,
   SPEC_VERSION,
   assertBundleSerializable,
@@ -39,7 +42,6 @@ import {
   deriveEdgeWriteItems,
   deriveEdgeWriteItemsFor,
   deriveModelEdgeWriteItems,
-  detectRelationFields,
   edgeWrites,
   encodeCursor,
   evaluateFilter,
@@ -53,7 +55,6 @@ import {
   executeQuery,
   from,
   getEdgeWrites,
-  getImplicitKeyFields,
   isCommandModelContract,
   isCommandPlan,
   isContractComposeNode,
@@ -65,6 +66,7 @@ import {
   isMutationFragment,
   isMutationInputRef,
   isPlannedCommandMethod,
+  isPreparedParamRef,
   isQueryModelContract,
   isTransactionRef,
   mapWithConcurrency,
@@ -72,6 +74,7 @@ import {
   mintContractParamRef,
   mutation,
   plan,
+  prepare,
   publicCommandModel,
   publicQueryModel,
   query,
@@ -80,7 +83,7 @@ import {
   validateDepth,
   when,
   wholeKeysSentinel
-} from "./chunk-Y7XV5QL2.js";
+} from "./chunk-GFGVDF4W.js";
 import {
   CdcEmulator,
   MAINT_OUTBOX_PK_PREFIX,
@@ -92,7 +95,7 @@ import {
   orderAndTrimCollection,
   pathField,
   projectFrom
-} from "./chunk-M6URQOAW.js";
+} from "./chunk-5NXNEW43.js";
 import {
   BATCH_GET_MAX_KEYS,
   BATCH_WRITE_MAX_ITEMS,
@@ -119,6 +122,7 @@ import {
   collectViewDefinitions,
   commitTransaction,
   cond,
+  detectRelationFields,
   entityWrites,
   execItemKeySignature,
   executeDelete,
@@ -126,6 +130,7 @@ import {
   executeTransaction,
   executeUpdate,
   getEntityWrites,
+  getImplicitKeyFields,
   gsi,
   hydrate,
   identity,
@@ -145,7 +150,7 @@ import {
   resolveConditionTree,
   resolveModelClass,
   serializeFieldValue
-} from "./chunk-CCIVET5K.js";
+} from "./chunk-F2DI3GTI.js";
 import {
   Linter,
   TableMapping,
@@ -512,6 +517,29 @@ function hasMany(targetFactory, keyBindingOrCallback, options) {
     });
   };
 }
+function refs(targetFactory, options) {
+  return function(_value, context) {
+    const propertyName = String(context.name);
+    assertRelationPropertyNameAllowed(propertyName);
+    if (!options || typeof options.from !== "string" || typeof options.key !== "string") {
+      throw new Error(
+        `@refs relation '${propertyName}': options must supply \`from\` (the parent list attribute, e.g. 'tagRefs') and \`key\` (the ref field on each element, e.g. 'tagId').`
+      );
+    }
+    const { from: from2, key: key2, to, ...relationOptions } = options;
+    const targetKeyField = to ?? key2;
+    collectRelation({
+      type: "refs",
+      propertyName,
+      targetFactory,
+      // Scalar keyBinding: target child key field ← element key name. Per resolved
+      // element the existing scalar key-building machinery reuses this unchanged.
+      keyBinding: { [targetKeyField]: key2 },
+      refs: { from: from2, key: key2 },
+      ...Object.keys(relationOptions).length > 0 ? { options: relationOptions } : {}
+    });
+  };
+}
 function belongsTo(targetFactory, keyBinding, options) {
   return function(_value, context) {
     const propertyName = String(context.name);
@@ -1850,6 +1878,9 @@ export {
   MaintenanceRebuilder,
   MetadataRegistry,
   OLD_VALUE_NAMESPACE,
+  PREPARE_CACHE_MAX,
+  PreparedReadStatement,
+  PreparedWriteStatement,
   RetryingExecutor,
   SPEC_VERSION,
   TableMapping,
@@ -1964,6 +1995,7 @@ export {
   isMutationInputRef,
   isParam,
   isPlannedCommandMethod,
+  isPreparedParamRef,
   isQueryModelContract,
   isRetryableError,
   isRetryableTransactionCancellation,
@@ -1989,11 +2021,13 @@ export {
   param,
   parseChange,
   plan,
+  prepare,
   preview,
   publicCommandModel,
   publicQueryModel,
   query,
   queryBoundaryRule,
+  refs,
   relationDepthRule,
   requireLimitRule,
   resolveKey,

package/dist/linter/index.d.ts

@@ -1,7 +1,7 @@
-import { L as LintRule } from '../registry-BD_5Rm5C.js';
-export { a as LintResult, b as Linter } from '../registry-BD_5Rm5C.js';
-export { c as createDefaultLinter, g as gsiAmbiguityRule, m as missingGsiRule, n as noScanRule, q as queryBoundaryRule, r as relationDepthRule, a as requireLimitRule } from '../relation-depth-DLkhG0xX.js';
-import '../maintenance-view-adapter-D5t9taTE.js';
+import { L as LintRule } from '../registry-Cv9nl_3i.js';
+export { a as LintResult, b as Linter } from '../registry-Cv9nl_3i.js';
+export { c as createDefaultLinter, g as gsiAmbiguityRule, m as missingGsiRule, n as noScanRule, q as queryBoundaryRule, r as relationDepthRule, a as requireLimitRule } from '../relation-depth-BR0y7Q1i.js';
+import '../maintenance-view-adapter-BP2CJDdz.js';
 import '@aws-sdk/client-dynamodb';
 
 /**