graphddb 0.3.0 → 0.4.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, F as FieldOptions, q as DynamoType, r as RelationOptions, A as AggregateOptions, s as AggregateValue, t as SelectBuilderSpec, u as RawCondition, v as TransactionSpec, w as Manifest, x as RetryOverride, y as ExecutionPlan, z as FieldMetadata, H 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, J as CdcEmulatorOptions, L as ChangeHandler, N as Unsubscribe, O as FaultSpec, Q as ConcurrentRecomputeRef, C as ChangeEvent, V as EventLog, X as ReplayOptions, Y as ShardId, Z as RelationMetadata, _ as TransactionItemSpec, $ as Param, a0 as ParamDescriptor, a1 as DefinitionMap, a2 as OperationDefinition, f as DDBModel, M as ModelStatic, a3 as WriteDefinitionOptions, a4 as PartialQueryKeyOf, a5 as StrictSelectSpec, a6 as EntityInput, a7 as UniqueQueryKeyOf, a8 as EntityRef, a9 as ConditionInput, aa as QueryModelContract, ab as QueryMethodSpec, ac as CommandModelContract, ad as CommandMethodSpec, ae as ContractSpec, af as QuerySpec, ag as CommandSpec, ah as ContextSpec, ai as OperationsDocument, aj as AnyOperationDefinition, ak as BridgeBundle, al as ConditionSpec } from './types-xJRn5qkv.js';
-export { am as AggregateMetadata, an as BatchDeleteRequest, ao as BatchGetOptions, ap as BatchGetRequest, aq as BatchGetResult, ar as BatchPutRequest, as as BatchResult, at as BatchWriteRequest, au as CONTRACT_RANGE_FANOUT_CONCURRENCY, av as CdcMode, aw as Change, ax as ChangeBatch, ay as ChangeEventName, az as ClockMode, aA as CollectionEffect, aB as CollectionOptions, aC as Column, aD as ColumnMap, aE as CommandContractMethodSpec, aF as CommandInputShape, aG as CommandMethod, aH as CommandPlan, aI as CommandResolutionTarget, aJ as CommandResultKind, aK as CommandSelectShape, aL as CompiledFragment, aM as ComposeSpec, aN as CondSlot, aO as ConditionCheckInput, aP as Connection, aQ as ContractCallSignature, aR as ContractCardinality, aS as ContractCommandParams, aT as ContractCommandResult, aU as ContractComposeNode, aV as ContractFromRef, aW as ContractInputArity, aX as ContractItem, aY as ContractKeyFieldRef, aZ as ContractKeyInput, a_ as ContractKeyRef, a$ as ContractKeySpec, b0 as ContractKind, b1 as ContractMethodOp, b2 as ContractParamRef, b3 as ContractQueryParams, b4 as ContractResolution, b5 as CounterAggregate, b6 as CounterEffect, b7 as CtxBase, b8 as DEFAULT_MAX_ATTEMPTS, b9 as DEFAULT_RETRY_POLICY, ba as DeleteOptions, bb as DeriveEffect, bc as DerivedEdgeWrite, bd as DerivedUpdate, be as DescriptorBinding, bf as ENTITY_WRITES_MARKER, bg as EdgeEffect, bh as EffectPath, bi as EmbeddedMetadata, bj as EmitEffect, bk as EntityWritesDefinition, bl as EntityWritesShape, bm as ExecutableCommandContract, bn as ExecutableQueryContract, bo as FilterInput, bp as FilterSpec, bq as FragmentInput, br as GsiDefinitionMarker, bs as GsiOptions, bt as IdempotencyEffect, bu as InProcessWriteDescriptor, bv as InputArity, bw as KeyDefinitionMarker, bx as KeySegment, by as KeySlot, bz as KeyStructure, bA as KeyedResult, bB as LIFECYCLE_CONTRACT_MARKER, bC as LifecycleContract, bD as LifecycleEffects, bE as LiteralParam, bF as MaintainConsistency, bG as MaintainEffect, bH as MaintainEvent, bI as MaintainItem, bJ as MaintainTrigger, bK as MaintainUpdateMode, bL as MaintenanceGraph, bM as ManifestEntity, bN as ManifestField, bO as ManifestFieldType, bP as ManifestGsi, bQ as ManifestKey, bR as ManifestRelation, bS as ManifestTable, bT as ModelRef, bU as MutateMode, bV as MutateOptions, bW as MutateParallelResult, bX as MutateTransactionResult, bY as MutationBody, bZ as MutationDescriptorMap, b_ as MutationFragment, b$ as MutationInputProxy, c0 as MutationInputRef, c1 as MutationIntent, c2 as NumberParam, c3 as OperationKind, c4 as OperationSpec, c5 as ParallelOpResult, c6 as ParamKind, c7 as ParamSpec, c8 as ParamStructure, c9 as PersistCtx, ca as PersistOrigin, cb as PlannedCommandMethod, cc as ProjectionMap, cd as ProjectionTransform, ce as ProjectionTransformOp, cf as PutOptions, cg as QueryContractMethodSpec, ch as QueryEnvelopeResult, ci as QueryKeyOf, cj as QueryMethod, ck as QueryResult, cl as RangeConditionSpec, cm as ReadEnvelope, cn as ReadOpCtx, co as ReadOpKind, cp as ReadOperationType, cq as ReadRouteDescriptor, cr as ReadRouteOptions, cs as ReadRouteResult, ct as RecordedCompose, cu as RelationBuilder, cv as RelationConsistency, cw as RelationLimitOptions, cx as RelationPattern, cy as RelationProjection, cz as RelationReadOptions, cA as RelationSelect, cB as RelationSpec, cC as RelationUpdateMode, cD as RelationWriteOptions, cE as RequiresEffect, cF as Resolution, cG as RetryInfo, cH as RetryOperationKind, cI as SPEC_VERSION, cJ as SegmentSpec, cK as SegmentedKey, cL as SelectBuilder, cM as SelectOf, cN as SnapshotEffect, cO as StartingPosition, cP as StreamViewType, cQ as StringParam, cR as TransactionContext, cS as TransactionItemType, cT as UniqueEffect, cU as Updatable, cV as UpdateOptions, cW as WhenSpec, cX as WriteCtx, cY as WriteDescriptor, cZ as WriteEnvelope, c_ as WriteInput, c$ as WriteKind, d0 as WriteLifecyclePhase, d1 as WriteMiddleware, d2 as WriteOperationType, d3 as WriteRecorder, d4 as WriteResultProjection, d5 as attachModelClass, d6 as buildDeleteInput, d7 as buildMaintenanceGraph, d8 as buildPutInput, d9 as buildUpdateInput, da as compileFragment, db as compileMutationPlan, dc as compileSingleFragmentPlan, dd as cond, de as contractOfMethodSpec, df as definePlan, dg as entityWrites, dh as executeBatchGet, di as executeBatchWrite, dj as executeCommandMethod, dk as executeDelete, dl as executeKeyedBatchGet, dm as executePut, dn as executeQueryMethod, dp as executeRangeFanout, dq as executeTransaction, dr as executeUpdate, ds as from, dt as getEntityWrites, du as gsi, dv as identity, dw as isColumn, dx as isCommandModelContract, dy as isCommandPlan, dz as isContractComposeNode, dA as isContractFromRef, dB as isContractKeyFieldRef, dC as isContractKeyRef, dD as isContractParamRef, dE as isEntityWritesDefinition, dF as isKeySegment, dG as isLifecycleContract, dH as isMaintainTrigger, dI as isMutationFragment, dJ as isMutationInputRef, dK as isParam, dL as isPlannedCommandMethod, dM as isQueryModelContract, dN as isRetryableError, dO as isRetryableTransactionCancellation, dP as k, dQ as key, dR as lifecyclePhaseForIntent, dS as maintainTrigger, dT as mintContractKeyFieldRef, dU as mintContractParamRef, dV as mutation, dW as param, dX as preview, dY as publicCommandModel, dZ as publicQueryModel, d_ as query, d$ as resolveLifecycle, e0 as wholeKeysSentinel } from './types-xJRn5qkv.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 EntityInput, ag as UniqueQueryKeyOf, ah as EntityRef, ai as ConditionInput, aj as QueryModelContract, ak as QueryMethodSpec, al as CommandModelContract, am as CommandMethodSpec, an as ContractSpec, ao as QuerySpec, ap as CommandSpec, aq as ContextSpec, ar as OperationsDocument, as as AnyOperationDefinition, at as BridgeBundle, au as ConditionSpec } from './types-CpCo8yHP.js';
+export { av as AggregateMetadata, aw as BatchDeleteRequest, ax as BatchGetOptions, ay as BatchGetRequest, az as BatchGetResult, aA as BatchPutRequest, aB as BatchResult, aC as BatchWriteRequest, aD as CONTRACT_RANGE_FANOUT_CONCURRENCY, aE as CdcMode, aF as Change, aG as ChangeBatch, aH as ChangeEventName, aI as ClockMode, aJ as CollectionEffect, aK as CollectionOptions, aL as Column, aM as ColumnMap, aN as CommandContractMethodSpec, aO as CommandInputShape, aP as CommandMethod, aQ as CommandPlan, aR as CommandResolutionTarget, aS as CommandResultKind, aT as CommandSelectShape, aU as CompiledFragment, aV as ComposeSpec, aW as CondSlot, aX as ConditionCheckInput, aY as Connection, aZ as ContractCallSignature, a_ as ContractCardinality, a$ as ContractCommandParams, b0 as ContractCommandResult, b1 as ContractComposeNode, b2 as ContractFromRef, b3 as ContractInputArity, b4 as ContractItem, b5 as ContractKeyFieldRef, b6 as ContractKeyInput, b7 as ContractKeyRef, b8 as ContractKeySpec, b9 as ContractKind, ba as ContractMethodOp, bb as ContractParamRef, bc as ContractQueryParams, bd as ContractResolution, be as CounterAggregate, bf as CounterEffect, bg as CtxBase, bh as DEFAULT_MAX_ATTEMPTS, bi as DEFAULT_RETRY_POLICY, bj as DeleteOptions, bk as DeriveEffect, bl as DerivedEdgeWrite, bm as DerivedUpdate, bn as DescriptorBinding, bo as ENTITY_WRITES_MARKER, bp as EdgeEffect, bq as EffectPath, br as EmbeddedMetadata, bs as EmitEffect, bt as EntityWritesDefinition, bu as EntityWritesShape, bv as ExecutableCommandContract, bw as ExecutableQueryContract, bx as FilterInput, by as FilterSpec, bz as FragmentInput, bA as GsiDefinitionMarker, bB as GsiOptions, bC as IdempotencyEffect, bD as InProcessWriteDescriptor, bE as InputArity, bF as KeyDefinitionMarker, bG as KeySegment, bH as KeySlot, bI as KeyStructure, bJ as KeyedResult, bK as LIFECYCLE_CONTRACT_MARKER, bL as LifecycleContract, bM as LifecycleEffects, bN as LiteralParam, bO as MaintainItem, bP as MaintainTrigger, bQ as MaintenanceGraph, bR as ManifestEntity, bS as ManifestField, bT as ManifestFieldType, bU as ManifestGsi, bV as ManifestKey, bW as ManifestRelation, bX as ManifestTable, bY as MembershipEffect, bZ as ModelRef, b_ as MutateMode, b$ as MutateOptions, c0 as MutateParallelResult, c1 as MutateTransactionResult, c2 as MutationBody, c3 as MutationDescriptorMap, c4 as MutationFragment, c5 as MutationInputProxy, c6 as MutationInputRef, c7 as MutationIntent, c8 as NumberParam, c9 as OperationKind, ca as OperationSpec, cb as ParallelOpResult, cc as ParamKind, cd as ParamSpec, ce as ParamStructure, cf as PersistCtx, cg as PersistOrigin, ch as PlannedCommandMethod, ci as ProjectionMap, cj as ProjectionTransformOp, ck as PutOptions, cl as QueryContractMethodSpec, cm as QueryEnvelopeResult, cn as QueryKeyOf, co as QueryMethod, cp as QueryResult, cq as RangeConditionSpec, cr as ReadEnvelope, cs as ReadOpCtx, ct as ReadOpKind, cu as ReadOperationType, cv as ReadRouteDescriptor, cw as ReadRouteOptions, cx as ReadRouteResult, cy as RecordedCompose, cz as RelationBuilder, cA as RelationConsistency, cB as RelationLimitOptions, cC as RelationPattern, cD as RelationProjection, cE as RelationReadOptions, cF as RelationSelect, cG as RelationSpec, cH as RelationUpdateMode, cI as RelationWriteOptions, cJ as RequiresEffect, cK as Resolution, cL as RetryInfo, cM as RetryOperationKind, cN as SPEC_VERSION, cO as SegmentSpec, cP as SegmentedKey, cQ as SelectBuilder, cR as SelectOf, cS as SnapshotEffect, cT as StartingPosition, cU as StreamViewType, cV as StringParam, cW as TransactionContext, cX as TransactionItemType, cY as UniqueEffect, cZ as Updatable, c_ as UpdateOptions, c$ as ViewSourceSlice, d0 as WhenSpec, d1 as WriteCtx, d2 as WriteDescriptor, d3 as WriteEnvelope, d4 as WriteInput, d5 as WriteKind, d6 as WriteLifecyclePhase, d7 as WriteMiddleware, d8 as WriteOperationType, d9 as WriteRecorder, da as WriteResultProjection, db as attachModelClass, dc as buildDeleteInput, dd as buildMaintenanceGraph, de as buildPutInput, df as buildUpdateInput, dg as collectViewDefinitions, dh as compileFragment, di as compileMutationPlan, dj as compileSingleFragmentPlan, dk as cond, dl as contractOfMethodSpec, dm as definePlan, dn as entityWrites, dp as executeBatchGet, dq as executeBatchWrite, dr as executeCommandMethod, ds as executeDelete, dt as executeKeyedBatchGet, du as executePut, dv as executeQueryMethod, dw as executeRangeFanout, dx as executeTransaction, dy as executeUpdate, dz as from, dA as getEntityWrites, dB as gsi, dC as identity, dD as isColumn, dE as isCommandModelContract, dF as isCommandPlan, dG as isContractComposeNode, dH as isContractFromRef, dI as isContractKeyFieldRef, dJ as isContractKeyRef, dK as isContractParamRef, dL as isEntityWritesDefinition, dM as isKeySegment, dN as isLifecycleContract, dO as isMaintainTrigger, dP as isMutationFragment, dQ as isMutationInputRef, dR as isParam, dS as isPlannedCommandMethod, dT as isQueryModelContract, dU as isRetryableError, dV as isRetryableTransactionCancellation, dW as k, dX as key, dY as lifecyclePhaseForIntent, dZ as maintainTrigger, d_ as mintContractKeyFieldRef, d$ as mintContractParamRef, e0 as mutation, e1 as param, e2 as preview, e3 as publicCommandModel, e4 as publicQueryModel, e5 as query, e6 as resolveLifecycle, e7 as wholeKeysSentinel } from './types-CpCo8yHP.js';
 import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
 import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
 
@@ -378,6 +378,14 @@ declare function validateGsiAmbiguity(primaryKey: KeyDefinition | null, gsiDefin
 interface ModelOptions {
     table: string;
     prefix?: string;
+    /**
+     * The model's maintenance kind (issue #152). Defaults to `'entity'` (a plain
+     * stored entity). `'materializedView'` / `'sparseView'` mark it a maintained view
+     * row whose `@maintainedFrom` declarations feed the maintenance graph. A
+     * `sparseView` requires every `@maintainedFrom` to carry a `when` predicate (the
+     * adapter validates this).
+     */
+    kind?: ModelKind;
 }
 declare function model(options: ModelOptions): (target: Function, context: ClassDecoratorContext) => void;
 
@@ -481,9 +489,294 @@ declare const map: FieldDecorator<Record<string, unknown>>;
 
 declare function embedded(modelFactory: () => new (...args: unknown[]) => unknown): (_value: undefined, context: ClassFieldDecoratorContext) => void;
 
-declare function hasMany(targetFactory: () => new (...args: unknown[]) => unknown, keyBinding: Record<string, string>, options?: RelationOptions): (_value: undefined, context: ClassFieldDecoratorContext) => void;
+/**
+ * Symbolic `(self, source) =>` evaluation for the `@maintainedFrom` view authoring
+ * and the versioned relation `pattern` union (issue #152).
+ *
+ * ## Why this module exists (existing-mechanism reuse, not a new invention)
+ *
+ * `key()` / `gsi()` already evaluate an author callback by handing it a **Proxy
+ * accessor** (`createColumnMap`, `src/select/column.ts`): any `c.<field>` access
+ * returns a branded {@link import('../select/column.js').Column} sentinel carrying
+ * the field NAME, never a real value — so the structure (which field is
+ * referenced, where) is captured verbatim and a value transform is structurally
+ * impossible. The maintained-authoring `(self, source) =>` callback is the SAME
+ * shape of problem (capture *which* source/self field fills *which* output slot,
+ * declaratively), so it reuses the SAME Proxy-sentinel mechanism, specialized to
+ * the two roots the maintained vocabulary needs:
+ *
+ * - **`source.<field>`** → a {@link SourceRef} sentinel whose `path` is the
+ *   payload-rooted `$.entity.<field>` the existing maintenance IR
+ *   ({@link import('../define/entity-writes.js').ProjectionTransform}) reads. This
+ *   is the value position (a projected value / key value / order-by / predicate
+ *   operand). Typed `keyof Source`.
+ * - **`self.<field>`** → a {@link SelfRef} sentinel naming a field of the view /
+ *   relation-target model (the `collection.field` position — which view attribute
+ *   holds the maintained list). Typed `keyof Self`.
+ *
+ * The output-attribute *names* (the keys of `keyBind` / `project`) are plain
+ * `keyof Self` string literals — NOT computed keys — exactly the "key = name
+ * (typed string), value = reference (proxy)" rule the issue fixes.
+ *
+ * The lowering target is UNCHANGED: a {@link SourceRef} lowers to the same
+ * `$.entity.<field>` path the old string-based builder produced, so the maintenance
+ * IR (`ViewSourceSlice` / `MaintainEffect`) is byte-identical — only the authoring
+ * surface (this symbolic capture) is new.
+ */
+
+/** Brand identifying a {@link SourceRef} (`source.<field>`) at runtime. */
+declare const SOURCE_REF: unique symbol;
+/** Brand identifying a {@link SelfRef} (`self.<field>`) at runtime. */
+declare const SELF_REF: unique symbol;
+/**
+ * A captured reference to a **source** field (`source.<field>`), the value
+ * position of the maintained vocabulary. Carries the field name and the
+ * payload-rooted `$.entity.<field>` {@link path} the maintenance IR reads. Branded
+ * so the adapter can distinguish a faithful reference from a literal and reject a
+ * coerced / mis-used reference loudly.
+ */
+interface SourceRef {
+    readonly [SOURCE_REF]: true;
+    /** The source field name (e.g. `authorId`). */
+    readonly field: string;
+    /** The payload-rooted source value path (`$.entity.<field>`). */
+    readonly path: string;
+}
+/**
+ * A captured reference to a **self** field (`self.<field>`), naming a field of the
+ * model being defined (the view / relation-target). Used in the `collection.field`
+ * position (which attribute holds the maintained list). Branded.
+ */
+interface SelfRef {
+    readonly [SELF_REF]: true;
+    /** The self (view / relation-target) field name (e.g. `latestPosts`). */
+    readonly field: string;
+}
+/**
+ * The typed `source` accessor handed to a `(self, source) =>` callback: one
+ * {@link SourceRef} per field of the source entity, each typed with the field's
+ * declared value type (so `preview(source.body, n)` type-checks against a string
+ * field and a key-value position type-checks against the bound view-key field).
+ *
+ * @typeParam S - The source entity instance type.
+ */
+type SourceProxy<S> = [unknown] extends [S] ? Readonly<Record<string, SourceRef>> : {
+    readonly [K in keyof S]-?: SourceRef & {
+        readonly __value?: S[K];
+    };
+};
+/**
+ * The typed `self` accessor handed to a `(self, source) =>` callback: one
+ * {@link SelfRef} per field of the model being defined. Used in the value position
+ * of `collection.field` (which self attribute holds the maintained collection).
+ *
+ * @typeParam T - The model (view / relation-target) instance type.
+ */
+type SelfProxy<T> = [unknown] extends [T] ? Readonly<Record<string, SelfRef>> : {
+    readonly [K in keyof T]-?: SelfRef & {
+        readonly __value?: T[K];
+    };
+};
+/**
+ * A projected value in a maintained `project` map: either a {@link SourceRef}
+ * (identity capture of a source field) or an explicit {@link ProjectionTransform}
+ * (e.g. `preview(source.body, 120)`). This is the value side of the "key = name,
+ * value = reference" rule; the key side is a `keyof Self` string literal.
+ */
+type ProjectionValue = SourceRef | ProjectionTransform;
+
+/**
+ * `@maintainedFrom` — the class-level, decorator-declarative view authoring of
+ * issue #152 (the Contract-layer replacement for `defineView` / `ViewRegistry`).
+ *
+ * ## What it is
+ *
+ * A maintained **view** (`@model({ kind: 'materializedView' | 'sparseView' })`) is
+ * its own modelled row maintained from the lifecycle events of one or more source
+ * entities. Each source contributes via a CLASS-LEVEL `@maintainedFrom` decorator
+ * (stackable — multiple sources each fill different view fields). This is the
+ * `@model`/`@hasMany` collector流儀: each `@maintainedFrom` pushes a
+ * {@link MaintainedFromMetadata} into a module-level collector and `@model` drains
+ * it into `EntityMetadata.maintainedFrom`.
+ *
+ * ## Symbolic `(self, source) =>` evaluation (existing-mechanism reuse)
+ *
+ * The options are authored as a `(self, source) => ({...})` callback evaluated
+ * eagerly at decoration time with the SAME Proxy-sentinel mechanism `key()`/`gsi()`
+ * use (`src/decorators/maintained-symbolic.ts`):
+ *
+ * - `source.<field>` → a {@link SourceRef} (value position) lowering to
+ *   `$.entity.<field>` — the exact path the old string builder produced, so the IR
+ *   is byte-identical.
+ * - `self.<field>` → a {@link SelfRef} naming a view field (the `collection.field`
+ *   position).
+ * - Object KEYS (`keyBind` / `project` left-hand side) stay `keyof Self` string
+ *   literals (NOT computed keys).
+ * - `on: ['created' | 'updated' | 'removed'][]` — the source is the decorator's
+ *   first argument, so the `'Post.created'` logical-name string is gone (the bug
+ *   class #124/#130 hit is removed by construction).
+ *
+ * ## Order independence (issue #152 hardening)
+ *
+ * Stacking order carries NO meaning. The adapter
+ * (`src/relation/maintenance-view-adapter.ts`) rejects — at build time, loudly and
+ * symmetrically (same error whichever order the decorators are stacked) — any two
+ * `@maintainedFrom` declarations that write the SAME projection target, the SAME
+ * `collection.field`, or bind the SAME view-key field inconsistently. A legitimate
+ * multi-source view (different sources filling DIFFERENT fields) is fine.
+ */
+
+type AnyModelClass$1 = new (...args: any[]) => any;
+type SourceFactory = () => AnyModelClass$1;
+/**
+ * A map keyed by `keyof Self` (the typed view fields) with value type `V`. When
+ * `Self` is left at its `unknown` default (the un-annotated decorator), it widens to
+ * a permissive `Record<string, V>` so authoring works without an explicit generic;
+ * supply `Self` to get `keyof Self` key-name checking.
+ */
+type SelfKeyed<Self, V> = [unknown] extends [Self] ? Readonly<Record<string, V>> : {
+    readonly [K in keyof Self]?: V;
+};
+/**
+ * The author-facing options object a `@maintainedFrom` callback returns. Keys
+ * (`keyBind` / `project` left-hand side) are `keyof Self` string literals; values
+ * are symbolic {@link SourceRef} (`source.<field>`) / transforms / {@link SelfRef}
+ * (`self.<field>`). `collection` and `when` are mutually exclusive.
+ *
+ * @typeParam Self - The view model instance type (drives `keyof Self` keys).
+ */
+interface MaintainedFromOptions<Self = unknown> {
+    /** The lifecycle events of the source that maintain the view row. */
+    readonly on: readonly MaintainEvent[];
+    /**
+     * The view-row key binding: view-row key field (`keyof Self`) → a `source.<field>`
+     * reference resolving which view row this source event maintains.
+     */
+    readonly keyBind: SelfKeyed<Self, SourceRef>;
+    /**
+     * The projection of the source payload into the view row: target attribute
+     * (`keyof Self`) → a `source.<field>` reference or a transform (`preview(...)`).
+     */
+    readonly project: SelfKeyed<Self, ProjectionValue>;
+    /**
+     * Declares this source maintains a bounded, ordered COLLECTION slice of the view
+     * row. `field` is a `self.<field>` reference (which view attribute holds the
+     * list); `orderBy` is a `source.<field>` reference. Mutually exclusive with `when`.
+     */
+    readonly collection?: {
+        readonly field: SelfRef;
+        readonly maxItems?: number;
+        readonly order?: 'ASC' | 'DESC';
+        readonly orderBy?: SourceRef;
+    };
+    /** Sparse-view membership predicate (sparseView kind). Mutually exclusive with `collection`. */
+    readonly when?: MembershipPredicate;
+    readonly consistency?: MaintainConsistency;
+    readonly updateMode?: MaintainUpdateMode;
+}
+/** The `(self, source) =>` symbolic callback evaluated at decoration time. */
+type MaintainedFromCallback<Self, Source> = (self: SelfProxy<Self>, source: SourceProxy<Source>) => MaintainedFromOptions<Self>;
+/**
+ * Build a {@link MembershipPredicate} for a sparse view. The view row is PUT when
+ * the predicate holds and DELETED when it flips false. The operand is a symbolic
+ * `source.<field>` reference (or a bare path string) lowered to `$.entity.<field>`.
+ *
+ * Named `whenMember` (not `when`) to avoid colliding with the transaction-condition
+ * `when` helper.
+ *
+ * @example `whenMember(source.status, 'eq', 'active')`
+ * @example `whenMember(source.archived, 'falsy')`
+ */
+declare function whenMember(operand: SourceRef | string, op: MembershipPredicateOp, value?: unknown): MembershipPredicate;
+/**
+ * `@maintainedFrom(source, (self, source) => options)` — the class-level view
+ * maintainer decorator (issue #152). Stackable: apply once per source. Evaluates
+ * the symbolic callback at decoration time and records the lowered
+ * {@link MaintainedFromMetadata} into the collector for `@model` to drain.
+ *
+ * @typeParam Self   - The view model instance type (typed `keyof Self` keys).
+ * @typeParam Source - The source entity instance type (typed `source.<field>`).
+ *
+ * @example
+ * ```ts
+ * @model({ table: 'AppTable', kind: 'materializedView' })
+ * @maintainedFrom(() => PostModel, (self, source) => ({
+ *   keyBind: { userId: source.authorId, threadId: source.threadId },
+ *   on:      ['created', 'removed'],
+ *   project: { lastPostAt: source.createdAt, textPreview: preview(source.body, 120) },
+ *   collection: { field: self.latestPosts, orderBy: source.createdAt, order: 'DESC', maxItems: 20 },
+ * }))
+ * class UserThreadListModel extends DDBModel { … }
+ * ```
+ */
+declare function maintainedFrom<Self = unknown, Source = unknown>(source: SourceFactory, callback: MaintainedFromCallback<Self, Source>): (target: Function, context: ClassDecoratorContext) => void;
+
+/**
+ * Versioned relation `pattern` discriminated union (issue #152, section B).
+ *
+ * Versioned is "a preset that re-uses the core snapshot effect", so it rides on the
+ * `@hasOne` / `@hasMany` `pattern` discriminator instead of a dedicated decorator:
+ *
+ * - `@hasOne(() => Latest, (self, source) => ({ pattern: 'versionedLatest', on, project }))`
+ *   — a SINGLE maintained row, OVERWRITTEN per revision (keyed without the version).
+ * - `@hasMany(() => History, (self, source) => ({ pattern: 'versionedHistory', on, project }))`
+ *   — one APPENDED row per revision (keyed WITH the version).
+ *
+ * ## Three type-level guards (issue #152 B (a)/(b)/(c))
+ *
+ * (a) Per-pattern fields — the options union is discriminated on `pattern`, so each
+ *     member admits exactly its own fields.
+ * (b) Cardinality integrity — `versionedLatest` is only assignable to a `@hasOne`
+ *     callback's return and `versionedHistory` only to `@hasMany`'s, enforced by the
+ *     distinct callback option types {@link HasOneVersionedOptions} /
+ *     {@link HasManyVersionedOptions} the two decorators accept.
+ * (c) Symbolic refs — `source.<field>` is `keyof Source` and `project` keys are
+ *     `keyof Self`, via the shared {@link SourceProxy} / proxy-sentinel mechanism.
+ *
+ * Both lower to the SAME snapshot×2 IR the old `defineVersioned` produced (the
+ * adapter `src/relation/maintenance-view-adapter.ts` turns the recorded
+ * `RelationOptions.versioned` into `defineView`-shaped `ViewDefinition`s). The
+ * latest/history KEY binding is derived from the TARGET model's own key input fields
+ * (each bound from the same-named source field) — latest keys omit the version,
+ * history keys include it, by the two models' own `key` definitions.
+ */
+
+/** A versioned-latest options object (single overwritten row). */
+interface VersionedLatestOptions<Self = unknown> {
+    readonly pattern: 'versionedLatest';
+    readonly on: readonly MaintainEvent[];
+    readonly project: SelfKeyed<Self, ProjectionValue>;
+    readonly consistency?: MaintainConsistency;
+    readonly updateMode?: MaintainUpdateMode;
+}
+/** A versioned-history options object (append-only per-revision rows). */
+interface VersionedHistoryOptions<Self = unknown> {
+    readonly pattern: 'versionedHistory';
+    readonly on: readonly MaintainEvent[];
+    readonly project: SelfKeyed<Self, ProjectionValue>;
+    readonly consistency?: MaintainConsistency;
+    readonly updateMode?: MaintainUpdateMode;
+}
+/**
+ * The options a `@hasOne` versioned callback may return — `versionedLatest` ONLY.
+ * (Cardinality integrity: a `versionedHistory` on `@hasOne` is a type error.)
+ */
+type HasOneVersionedOptions<Self = unknown> = VersionedLatestOptions<Self>;
+/**
+ * The options a `@hasMany` versioned callback may return — `versionedHistory` ONLY.
+ * (Cardinality integrity: a `versionedLatest` on `@hasMany` is a type error.)
+ */
+type HasManyVersionedOptions<Self = unknown> = VersionedHistoryOptions<Self>;
+/** The `(self, source) =>` versioned callback for `@hasOne`. */
+type HasOneVersionedCallback<Self, Source> = (self: SelfProxy<Self>, source: SourceProxy<Source>) => HasOneVersionedOptions<Self>;
+/** The `(self, source) =>` versioned callback for `@hasMany`. */
+type HasManyVersionedCallback<Self, Source> = (self: SelfProxy<Self>, source: SourceProxy<Source>) => HasManyVersionedOptions<Self>;
+
+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;
 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>): (_value: undefined, context: ClassFieldDecoratorContext) => void;
+declare function hasOne(targetFactory: () => new (...args: unknown[]) => unknown, keyBinding: Record<string, string>): (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;
 
 /**
  * `@aggregate` — a **scalar-aggregate** field decorator (Epic #118 §5.2 counter /
@@ -1075,6 +1368,147 @@ declare class CdcEmulator {
 /** Create a CDC emulator (spec §10). */
 declare function createCdcEmulator(opts?: CdcEmulatorOptions): CdcEmulator;
 
+/**
+ * CDC **maintenance drain** (issue #130) — the asynchronous lower for
+ * `updateMode: 'stream'` maintainers (Epic #118 §5.1).
+ *
+ * A synchronous (`updateMode: 'mutation'`) maintainer composes its owner-row write
+ * into the SAME atomic `TransactWriteItems` as the source write (#127). A
+ * `updateMode: 'stream'` maintainer instead emits a **maintenance-outbox** marker row
+ * (`OUTBOX#MAINT#…`) ATOMICALLY with the source write (the #130 compile lowering in
+ * `src/spec/mutation-command.ts`), and THIS consumer — driven by the {@link
+ * import('./emulator.js').CdcEmulator} (or, in production, real DynamoDB Streams +
+ * a Lambda built around {@link createMaintenanceDrainHandler}) — applies the owner-row
+ * write asynchronously.
+ *
+ * ## Why a separate async path exists (not just "do it later synchronously")
+ *
+ * The async path realizes the maintenance operations a single synchronous
+ * `UpdateExpression` cannot express against an unread item:
+ *
+ * - **collection `maxItems` trim** — keeping a bounded, ordered list requires reading
+ *   the current list, appending, sorting, and trimming (a read-modify-write); a
+ *   synchronous `list_append` can only append (Phase 1 was append-only, #127).
+ * - **`removed`-driven splice** — removing an entry from a maintained collection on a
+ *   source `removed` event likewise needs the current list.
+ * - **running `max(field)`** — a conditional `SET` (`#a = :v` guarded by
+ *   `attribute_not_exists(#a) OR #a < :v`) whose failed guard, if run synchronously,
+ *   would roll back the legitimate source write.
+ *
+ * ## Delivery guarantees (reused from the CDC substrate)
+ *
+ * The maintenance-outbox row is recorded ATOMICALLY with the source write, so the
+ * intent can never be lost ("wrote the row, lost the maintenance" is impossible). The
+ * CDC substrate then delivers it **at-least-once**, **per-shard ordered** (a shard is
+ * `hash(pk)`, and the outbox row's `pk` is keyed off the SOURCE row's key, so all
+ * maintenance events for one source entity land on one shard in source-write order),
+ * with a **DLQ** for poison events. This consumer is therefore written to be
+ * **idempotent / commutative** wherever at-least-once redelivery could double-apply:
+ *
+ * - a `snapshot` `SET` is naturally idempotent (re-applying the same projection is a
+ *   no-op);
+ * - a `collection` rebuild de-duplicates by the projected item's identity key, so a
+ *   redelivered append does not grow the list twice;
+ * - a `max` conditional `SET` is idempotent (the guard rejects a non-greater value);
+ * - a `count` `ADD` is the ONE non-idempotent op — but the source-row create guard
+ *   (`attribute_not_exists`) means a given source `created` event is emitted at most
+ *   once into the outbox, and the per-shard checkpoint advances only over acked events,
+ *   so a `count` is applied once per genuine source lifecycle. (A duplicate DELIVERY of
+ *   the same event is folded by the consumer's per-event de-dup set within a drain.)
+ */
+
+/**
+ * The PK prefix a maintenance-outbox row keys on — the single source of truth shared
+ * with the compiler ({@link import('../spec/mutation-command.js')}'s
+ * `MAINT_OUTBOX_PK_PREFIX`). The drain selects its events by `keys.pk.startsWith` of
+ * this. Kept as a local literal (rather than importing a non-exported compiler const)
+ * so the cdc module does not depend on the spec module; the value is asserted equal by
+ * the integration tests that round-trip a real stream maintainer through both.
+ */
+declare const MAINT_OUTBOX_PK_PREFIX = "OUTBOX#MAINT#";
+/** Options for {@link createMaintenanceDrain}. */
+interface MaintenanceDrainOptions {
+    /**
+     * The model classes (or `ModelStatic`s) whose stream maintainers this drain
+     * applies. The drain builds a scoped {@link MaintenanceGraph} over them to resolve
+     * each maintenance-outbox event back to its declared effect. Defaults to the GLOBAL
+     * registry when omitted.
+     */
+    readonly models?: readonly Function[];
+    /**
+     * The {@link ViewDefinition}s (`defineView`) whose maintainers this drain applies
+     * (issue #132). A view's destination is its dedicated view model; its source
+     * classes should also be in {@link models} so the drain can resolve their
+     * maintenance-outbox events. Defaults to none.
+     */
+    readonly views?: readonly ViewDefinition[];
+}
+/**
+ * A maintenance drain: a CDC consumer ({@link ChangeHandler}) that applies the
+ * owner-row writes for `updateMode: 'stream'` maintainers. Construct via
+ * {@link createMaintenanceDrain}, then `subscribe` its {@link handler} to a
+ * {@link import('./emulator.js').CdcEmulator} (dev/test) or wire it into a real
+ * Streams Lambda (production).
+ */
+declare class MaintenanceDrain {
+    private readonly graph;
+    /** Owner entity name → its model class (for the owner-row key derivation). */
+    private readonly ownerByName;
+    /** Per-event-id de-dup within a single handler invocation (at-least-once). */
+    private appliedSeq;
+    /** Count of owner-row writes applied (test/diagnostic). */
+    private applied;
+    constructor(opts?: MaintenanceDrainOptions);
+    /** The CDC {@link ChangeHandler} to subscribe to an emulator / Streams source. */
+    readonly handler: ChangeHandler;
+    /** Resolve one maintenance-outbox event to its effect and apply the owner-row write. */
+    private applyOne;
+    /** Resolve a maintenance-outbox event back to the declared {@link MaintainItem}. */
+    private resolve;
+    /** A `snapshot` SET of each projected attribute onto the owner row (idempotent). */
+    private applySnapshot;
+    /**
+     * A sparse-view **membership** write (#133): evaluate the membership predicate against
+     * the source image; PUT the view row (its projection + key fields) when the predicate
+     * holds, DELETE it when it flips false. A source `removed` event always deletes (the
+     * source no longer exists, so its view row must disappear regardless of the predicate).
+     *
+     * Both ops are idempotent under at-least-once redelivery: a repeated PUT writes the same
+     * row, a repeated DELETE is a no-op. The view row is keyed by the source identity
+     * (`effect.keys`), so the PUT/DELETE always targets the SAME physical row the predicate
+     * gates.
+     */
+    private applyMembership;
+    /**
+     * A running `max`: read the owner row, and `SET` the attribute to the source value
+     * only when it is greater (or absent). Implemented as a conditional update so a
+     * redelivered / out-of-order older value never regresses the stored max — idempotent
+     * and commutative under at-least-once delivery.
+     */
+    private applyMax;
+    /**
+     * A bounded `collection`: read the current list, apply the event (append for a
+     * `created`/`updated` source, splice for a `removed`), de-duplicate by the projected
+     * identity key, order by `orderBy` (in `orderDir`, default DESC), trim to `maxItems`, and write the whole
+     * list back. The read-modify-write is exactly what a single synchronous
+     * `UpdateExpression` cannot do — the reason a bounded/ordered collection is a stream
+     * maintainer (Phase 1 sync was append-only).
+     */
+    private applyCollection;
+    /** Owner-row writes applied so far (test/diagnostic). */
+    appliedCount(): number;
+    /** Clear the per-delivery de-dup set + counters (test reset). */
+    reset(): void;
+}
+/** Create a {@link MaintenanceDrain} (issue #130). */
+declare function createMaintenanceDrain(opts?: MaintenanceDrainOptions): MaintenanceDrain;
+/**
+ * Create just the CDC {@link ChangeHandler} for a maintenance drain — the form to
+ * subscribe to an emulator or wire into a production Streams Lambda. A thin wrapper
+ * over {@link createMaintenanceDrain} for callers that only need the handler.
+ */
+declare function createMaintenanceDrainHandler(opts?: MaintenanceDrainOptions): ChangeHandler;
+
 /**
  * Per-key cursor envelope for batched `range` (`list`) contract methods (issue
  * #62, CQRS single-service runtime; spec `docs/cqrs-contract.md`,
@@ -1340,12 +1774,42 @@ type EdgeLifecycle = 'onCreate' | 'onDelete' | 'onUpdateKeyChange';
  * lifecycle-agnostic — the *same* edge is created on create, deleted on delete,
  * and moved on a foreign-key change; {@link deriveEdgeWriteItems} fans it out
  * into the three lifecycle forms.
+ *
+ * ## `inverse` — dual-edge synchronization (Epic #118 pattern 9, issue #133)
+ *
+ * The plain edge above is **one physical row** that serves *both* read directions:
+ * the base PK reads one direction and an inverse GSI (auto-maintained by DynamoDB)
+ * reads the other, so a bidirectional relation costs a single write. The RFC §1
+ * pattern-9 gap is the case where the inverse direction is NOT served by that GSI
+ * but by a **second physical row** on its own partition — the genuine *dual edge*
+ * (forward + inverse rows). {@link inverse}, when present, names a SECOND adjacency
+ * model + relation property whose row is the inverse edge; {@link
+ * deriveEdgeWriteItemsFor} then maintains BOTH rows from this single (one-direction)
+ * declaration — the create `Put`s both, the delete `Delete`s both, a foreign-key
+ * change `Delete`s+`Put`s both — so the two directions can never drift. Omit
+ * `inverse` for the historical single-row-plus-GSI bidirectional edge.
  */
 interface EdgeWriteDeclaration {
     /** Resolves the target model whose relation this edge feeds (e.g. `GroupModel`). */
     readonly targetFactory: () => new (...args: unknown[]) => unknown;
     /** The relation property on the target that reads this edge (e.g. `members`). */
     readonly relationProperty: string;
+    /**
+     * The INVERSE edge to keep in sync (Epic #118 pattern 9 / issue #133, dual-edge).
+     * Names the second adjacency model whose own row materializes the reverse-direction
+     * relation. When present, every lifecycle derivation maintains the inverse row
+     * alongside the forward row in the SAME transaction, so a one-direction declaration
+     * keeps a two-row bidirectional edge consistent. Absent = the historical single-row
+     * (base + inverse GSI) bidirectional edge.
+     */
+    readonly inverse?: {
+        /** Resolves the inverse adjacency model whose row IS the inverse edge. */
+        readonly adjacencyFactory: () => new (...args: unknown[]) => unknown;
+        /** Resolves the target model whose relation the inverse row feeds. */
+        readonly targetFactory: () => new (...args: unknown[]) => unknown;
+        /** The relation property on the inverse target that reads the inverse row. */
+        readonly relationProperty: string;
+    };
 }
 /**
  * Marker carried by a model's static `writes` member ({@link edgeWrites}), so it
@@ -1386,6 +1850,34 @@ interface EdgeWriteRecorder {
      * `relationProperty` relation (→ adjacency `Delete`(old) + `Put`(new)).
      */
     updateKeyChangeEdge(target: () => new (...args: unknown[]) => unknown, relationProperty: string): EdgeWriteDeclaration;
+    /**
+     * Declare a **dual edge** (Epic #118 pattern 9 / issue #133): a bidirectional edge
+     * maintained as TWO physical rows — a forward row on THIS adjacency entity (read by
+     * `forward.target.relationProperty`) and an inverse row on a SECOND adjacency model
+     * (read by `inverse.target.relationProperty`). Both rows are written / deleted /
+     * moved together from this single declaration, so the two directions stay in sync
+     * without an inverse GSI. Use this when the reverse direction lives on its own
+     * partition (a second row) rather than a GSI of the forward row.
+     *
+     * @example
+     * ```ts
+     * // On the forward adjacency entity (FollowEdge: FOLLOWER#a / FOLLOWING#b):
+     * static readonly writes = edgeWrites((w) => [
+     *   w.dualEdge(
+     *     { target: () => UserModel, relationProperty: 'following' },
+     *     { adjacency: () => FollowedByEdgeModel, target: () => UserModel, relationProperty: 'followers' },
+     *   ),
+     * ]);
+     * ```
+     */
+    dualEdge(forward: {
+        target: () => new (...args: unknown[]) => unknown;
+        relationProperty: string;
+    }, inverse: {
+        adjacency: () => new (...args: unknown[]) => unknown;
+        target: () => new (...args: unknown[]) => unknown;
+        relationProperty: string;
+    }): EdgeWriteDeclaration;
 }
 /**
  * Declare an adjacency entity's edge write side (issue #82), as the model's
@@ -1457,6 +1949,182 @@ declare function getEdgeWrites(modelClass: new (...args: unknown[]) => unknown):
  */
 declare function deriveModelEdgeWriteItems(modelClass: new (...args: unknown[]) => unknown, lifecycle: EdgeLifecycle): TransactionItemSpec[];
 
+/**
+ * Maintenance **repair / rebuild planner** (Epic #118 Phase 2, issue #131).
+ *
+ * ## What this is
+ *
+ * The async drain ({@link import('../cdc/maintenance-drain.js')}, #130) keeps a
+ * maintained owner row (a snapshot / collection / counter) in sync INCREMENTALLY —
+ * it applies one source event at a time. Over a long-lived table the materialized
+ * value can nevertheless **drift** from the source of truth: a dropped / dead-lettered
+ * stream event, a maintainer added AFTER source rows already existed (initial
+ * un-built state), a bug in an earlier maintainer version, or an out-of-band write.
+ *
+ * The rebuild planner is the repair for that drift. For a given owner row × maintainer
+ * it **re-derives the owner-row value from scratch by scanning every source row that
+ * belongs to that owner**, using the SAME projection / aggregation / ordering rules the
+ * drain uses (shared via `maintenance-projection.ts` and this module), then:
+ *
+ *  - **{@link detectDrift}** — compares the re-derived value against the value currently
+ *    stored on the owner row and reports whether (and how) they differ; or
+ *  - **{@link rebuild}** — writes the re-derived ABSOLUTE value onto the owner row, so the
+ *    materialized data converges to exactly what the source says.
+ *
+ * After a rebuild the owner row equals what an incremental drain would have converged to
+ * had it never missed an event — the AC: "rebuild で materialized が source と一致する".
+ *
+ * ## Granularity: per owner row × maintainer
+ *
+ * Drift is detected and repaired at the **owner-row × maintainer** grain — the natural
+ * unit, because one owner row's materialized value is a pure function of the set of
+ * source rows bound to it. The caller names the owner rows to repair (their key inputs);
+ * the planner discovers the source rows for each by querying the source on the maintenance
+ * key binding (the same binding the live `hasMany` / `@aggregate` read uses, inverted:
+ * the owner row supplies the binding value, the source partition is scanned for matches).
+ *
+ * ## count is re-derived as an ABSOLUTE SET, not an ADD
+ *
+ * The maintained counter applies a signed `ADD` per event (#141 / #130). A rebuild
+ * instead **counts the source rows and SETs the absolute value** — it does not trust the
+ * accumulated counter, it recomputes it. This is the whole point of repair (an ADD that
+ * has drifted cannot be corrected by another ADD). The `max(field)` counter is re-derived
+ * as the maximum over the scanned source rows and SET unconditionally (the rebuild is the
+ * authority, so it does not use the drain's advance-only conditional guard).
+ *
+ * ## Execution form (production positioning)
+ *
+ * Like the drain applier, this is a **TS-side planner/executor** intended for dev/test and
+ * **operational repair tooling** — run on-demand (a "repair this thread's summary now"
+ * admin action) or as a periodic batch (a scheduled reconciliation sweep over a set of
+ * owner rows). It is NOT injected into the SSoT spec and emits no generated artifact: a
+ * rebuild is a host-side reconciliation against live DynamoDB, not part of a model's
+ * compiled write contract — so there is no Python mirror (the Python runtime executes the
+ * generated contract; rebuild is not in it). It reuses the maintenance graph (#124) to
+ * resolve which maintainers exist and the shared re-derivation rules so a rebuilt value is
+ * byte-consistent with a drained one.
+ */
+
+/** A model class (or `ModelStatic`) the rebuild planner operates over. */
+type ModelLike = Function | ModelStatic<DDBModel>;
+/** Options for {@link createMaintenanceRebuilder}. */
+interface MaintenanceRebuildOptions {
+    /**
+     * The model classes whose maintainers this rebuilder can repair. The rebuilder
+     * builds a scoped {@link MaintenanceGraph} over them to resolve each
+     * owner-row × maintainer back to its declared effect. Defaults to the GLOBAL
+     * registry when omitted.
+     */
+    readonly models?: readonly ModelLike[];
+    /**
+     * The {@link ViewDefinition}s (`defineView`) whose maintainers this rebuilder can
+     * repair (issue #132). The view model classes are added to the scoped registry so a
+     * view row can be re-derived from its source rows, exactly like a relation owner row.
+     */
+    readonly views?: readonly ViewDefinition[];
+}
+/**
+ * The drift verdict for one owner row × maintainer: whether the currently-stored
+ * materialized value differs from the value re-derived from the source rows, and both
+ * values (for diagnostics / a repair preview). `expected` is the re-derived authority;
+ * `actual` is what the owner row currently holds (`undefined` when never built).
+ */
+interface DriftReport {
+    /** The relation / aggregate property the maintained value lives under. */
+    readonly relationProperty: string;
+    /** The owner entity (logical name) the row belongs to. */
+    readonly ownerEntity: string;
+    /** The owner row's resolved key (`{ PK, SK }`). */
+    readonly ownerKey: Record<string, unknown>;
+    /** The maintained attribute (collection field / snapshot attrs / counter attribute). */
+    readonly kind: MaintainEffect['kind'];
+    /** True when `actual` differs from `expected` (drift present). */
+    readonly drifted: boolean;
+    /** The value re-derived from the source rows (the authority). */
+    readonly expected: unknown;
+    /** The value currently stored on the owner row (`undefined` when unbuilt). */
+    readonly actual: unknown;
+}
+/** The outcome of a {@link MaintenanceRebuilder.rebuild} over one owner row × maintainer. */
+interface RebuildResult extends DriftReport {
+    /** True when the owner row was written (drift was present and repaired). */
+    readonly repaired: boolean;
+}
+/**
+ * A maintenance **repair / rebuild planner** (#131). Construct via
+ * {@link createMaintenanceRebuilder}, then call {@link detectDrift} to compare or
+ * {@link rebuild} to repair one owner row × maintainer (resolved by the owner model +
+ * the relation/aggregate property + the owner key inputs).
+ */
+declare class MaintenanceRebuilder {
+    private readonly graph;
+    constructor(opts?: MaintenanceRebuildOptions);
+    /**
+     * Re-derive the materialized value for one owner row × maintainer from the source
+     * rows and report whether it differs from what the owner row currently stores. Does
+     * NOT write anything (a read-only drift probe).
+     *
+     * @param owner The owner model class declaring the maintainer.
+     * @param relationProperty The relation / `@aggregate` property the value lives under.
+     * @param ownerKeyInput The owner row's key input (e.g. `{ threadId: 't1' }`).
+     */
+    detectDrift(owner: ModelLike, relationProperty: string, ownerKeyInput: Record<string, unknown>): Promise<DriftReport>;
+    /**
+     * Re-derive the materialized value for one owner row × maintainer from the source
+     * rows and WRITE the absolute re-derived value onto the owner row when it drifts (or
+     * always, when `force`). Returns the drift verdict plus whether a repair write ran.
+     *
+     * @param options.force Write even when no drift is detected (default: write only on drift).
+     */
+    rebuild(owner: ModelLike, relationProperty: string, ownerKeyInput: Record<string, unknown>, options?: {
+        force?: boolean;
+    }): Promise<RebuildResult>;
+    /** Resolve an owner model + property to its {@link MaintainItem} + owner-key builder. */
+    private resolve;
+    /**
+     * Scan every source row bound to this owner row and re-derive the maintained value:
+     *
+     *  - **collection** — project each source row, order + trim by the SAME read-side
+     *    rules (`orderBy` / `orderDir` / `maxItems`) the drain uses, return the list;
+     *  - **snapshot** — project the single bound source row (or `undefined` when none);
+     *  - **counter `count`** — the COUNT of source rows (absolute, not an ADD);
+     *  - **counter `max`** — the maximum source value of the tracked field.
+     */
+    private recompute;
+    /**
+     * The source rows bound to one owner row. The maintenance key binding is
+     * `{ ownerField: '$.entity.<sourceField>' }` (the destination owner-key field ← the
+     * source row's field). INVERTED for a rebuild: the owner row supplies the value, and
+     * the source partition is queried for rows whose `<sourceField>` matches — exactly the
+     * set the live `hasMany` / `@aggregate` read aggregates. Queries the source via the
+     * same {@link plan} the read planner uses (a partition Query), paginating fully.
+     */
+    private scanSourceRows;
+    /** Re-derive a bounded collection: project, then order + trim by the read-side rules. */
+    private recomputeCollection;
+    /**
+     * Re-derive a single-row snapshot. A snapshot mirrors ONE source row (a `belongsTo` /
+     * `hasOne`, normally 1:1). In the unusual case where MORE THAN ONE source row binds, the
+     * live single-value read takes the FIRST row in the source's natural query order
+     * (`ScanIndexForward`, default ASC = the smallest sort-key leaf), so re-derive the same
+     * row — {@link pickFirst} — for a verdict consistent with the live read. Returns
+     * `undefined` when no source row is bound (the snapshot should be absent).
+     */
+    private recomputeSnapshot;
+    /** The source entity metadata a maintain effect projects from (its relation target). */
+    private sourceMetaOf;
+    /** Re-derive a counter: the absolute COUNT of source rows, or the MAX of the tracked field. */
+    private recomputeCounter;
+    /** Read the owner row (consistent) for the drift comparison / actual value. */
+    private readOwnerRow;
+    /** The value currently stored on the owner row for this maintainer. */
+    private actualValue;
+    /** Write the re-derived ABSOLUTE value onto the owner row (the repair). */
+    private writeValue;
+}
+/** Create a {@link MaintenanceRebuilder} (issue #131). */
+declare function createMaintenanceRebuilder(opts?: MaintenanceRebuildOptions): MaintenanceRebuilder;
+
 /**
  * Type-level machinery for the parameterized definition DSL (issue #41).
  *
@@ -2328,4 +2996,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, 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, Item, KeyDefinition, type LintResult, type LintRule, Linter, type ListInput, type ListOptions, MAX_TRANSACT_ITEMS, Manifest, MetadataRegistry, Middleware, type ModelOptions, ModelStatic, OLD_VALUE_NAMESPACE, OperationDefinition, OperationsDocument, Param, ParamDescriptor, type Parameterize, PartialQueryKeyOf, type PerKeyCursorEnvelope, type PlanInput, PrimaryKeyOf, type ProjectionResult, PutInput, QueryMethodSpec, QueryModelContract, type QueryOptions$1 as QueryOptions, QuerySpec, RawCondition, ReadExecOptions, ReadParams, ReadRequestCtx, ReadRequestKind, RelationMetadata, RelationOptions, type RelationTraversalOptions, ReplayOptions, RequestContext, ResolvedKey, RetryOverride, RetryPolicy, RetryingExecutor, SelectableOf, ShardId, 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 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, 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, map, max, missingGsiRule, model, noScanRule, number, numberSet, plan, queryBoundaryRule, relationDepthRule, requireLimitRule, resolveKey, resolveRelations, serializeContractKey, serializeFieldValue, string, stringSet, validateDepth, validateGsiAmbiguity, when };
+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 };