graphddb 0.2.5 → 0.3.1

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { S as SelectableOf, g as PrimaryKeyOf, h as RequestContext, i as Middleware, j as ReadRequestKind, k as CtxModel, l as ReadParams, m as ReadRequestCtx, D as DynamoDBOperation, I as Item, E as Executor, n as RetryPolicy, o as ExecutionPlanSpec, p as SegmentedKey, q as SelectBuilderSpec, r as RawCondition, s as TransactionSpec, t as Manifest, u as RetryOverride, v as ExecutionPlan, w 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, x as CdcEmulatorOptions, y as ChangeHandler, z as Unsubscribe, F as FaultSpec, A as ConcurrentRecomputeRef, C as ChangeEvent, G as EventLog, H as ReplayOptions, J as ShardId, K as TransactionItemSpec, L as Param, N as ParamDescriptor, O as DefinitionMap, Q as OperationDefinition, f as DDBModel, M as ModelStatic, V as WriteDefinitionOptions, X as PartialQueryKeyOf, Y as StrictSelectSpec, Z as EntityInput, _ as UniqueQueryKeyOf, $ as EntityRef, a0 as ConditionInput, a1 as QueryModelContract, a2 as QueryMethodSpec, a3 as CommandModelContract, a4 as CommandMethodSpec, a5 as ContractSpec, a6 as QuerySpec, a7 as CommandSpec, a8 as ContextSpec, a9 as OperationsDocument, aa as AnyOperationDefinition, ab as BridgeBundle, ac as ConditionSpec } from './types--tdHK3vi.js';
-export { ad as BatchDeleteRequest, ae as BatchGetOptions, af as BatchGetRequest, ag as BatchGetResult, ah as BatchPutRequest, ai as BatchResult, aj as BatchWriteRequest, ak as CONTRACT_RANGE_FANOUT_CONCURRENCY, al as CdcMode, am as Change, an as ChangeBatch, ao as ChangeEventName, ap as ClockMode, aq as Column, ar as ColumnMap, as as CommandContractMethodSpec, at as CommandInputShape, au as CommandMethod, av as CommandPlan, aw as CommandResolutionTarget, ax as CommandResultKind, ay as CommandSelectShape, az as CompiledFragment, aA as ComposeSpec, aB as CondSlot, aC as ConditionCheckInput, aD as Connection, aE as ContractCallSignature, aF as ContractCardinality, aG as ContractCommandParams, aH as ContractCommandResult, aI as ContractComposeNode, aJ as ContractFromRef, aK as ContractInputArity, aL as ContractItem, aM as ContractKeyFieldRef, aN as ContractKeyInput, aO as ContractKeyRef, aP as ContractKeySpec, aQ as ContractKind, aR as ContractMethodOp, aS as ContractParamRef, aT as ContractQueryParams, aU as ContractResolution, aV as CtxBase, aW as DEFAULT_MAX_ATTEMPTS, aX as DEFAULT_RETRY_POLICY, aY as DeleteOptions, aZ as DeriveEffect, a_ as DerivedEdgeWrite, a$ as DerivedUpdate, b0 as DescriptorBinding, b1 as ENTITY_WRITES_MARKER, b2 as EdgeEffect, b3 as EffectPath, b4 as EmitEffect, b5 as EntityWritesDefinition, b6 as EntityWritesShape, b7 as ExecutableCommandContract, b8 as ExecutableQueryContract, b9 as FilterInput, ba as FilterSpec, bb as FragmentInput, bc as GsiDefinitionMarker, bd as GsiOptions, be as IdempotencyEffect, bf as InProcessWriteDescriptor, bg as InputArity, bh as KeyDefinitionMarker, bi as KeySegment, bj as KeySlot, bk as KeyStructure, bl as KeyedResult, bm as LIFECYCLE_CONTRACT_MARKER, bn as LifecycleContract, bo as LifecycleEffects, bp as LiteralParam, bq as ManifestEntity, br as ManifestField, bs as ManifestFieldType, bt as ManifestGsi, bu as ManifestKey, bv as ManifestRelation, bw as ManifestTable, bx as ModelRef, by as MutateMode, bz as MutateOptions, bA as MutateParallelResult, bB as MutateTransactionResult, bC as MutationBody, bD as MutationDescriptorMap, bE as MutationFragment, bF as MutationInputProxy, bG as MutationInputRef, bH as MutationIntent, bI as NumberParam, bJ as OperationKind, bK as OperationSpec, bL as ParallelOpResult, bM as ParamKind, bN as ParamSpec, bO as ParamStructure, bP as PersistCtx, bQ as PersistOrigin, bR as PlannedCommandMethod, bS as PutOptions, bT as QueryContractMethodSpec, bU as QueryEnvelopeResult, bV as QueryKeyOf, bW as QueryMethod, bX as QueryResult, bY as RangeConditionSpec, bZ as ReadEnvelope, b_ as ReadOpCtx, b$ as ReadOpKind, c0 as ReadOperationType, c1 as ReadRouteDescriptor, c2 as ReadRouteOptions, c3 as ReadRouteResult, c4 as RecordedCompose, c5 as RelationBuilder, c6 as RelationSelect, c7 as RelationSpec, c8 as RequiresEffect, c9 as Resolution, ca as RetryInfo, cb as RetryOperationKind, cc as SPEC_VERSION, cd as SegmentSpec, ce as SelectBuilder, cf as SelectOf, cg as StartingPosition, ch as StreamViewType, ci as StringParam, cj as TransactionContext, ck as TransactionItemType, cl as UniqueEffect, cm as Updatable, cn as UpdateOptions, co as WhenSpec, cp as WriteCtx, cq as WriteDescriptor, cr as WriteEnvelope, cs as WriteInput, ct as WriteKind, cu as WriteLifecyclePhase, cv as WriteMiddleware, cw as WriteOperationType, cx as WriteRecorder, cy as WriteResultProjection, cz as attachModelClass, cA as buildDeleteInput, cB as buildPutInput, cC as buildUpdateInput, cD as compileFragment, cE as compileMutationPlan, cF as compileSingleFragmentPlan, cG as cond, cH as contractOfMethodSpec, cI as definePlan, cJ as entityWrites, cK as executeBatchGet, cL as executeBatchWrite, cM as executeCommandMethod, cN as executeDelete, cO as executeKeyedBatchGet, cP as executePut, cQ as executeQueryMethod, cR as executeRangeFanout, cS as executeTransaction, cT as executeUpdate, cU as from, cV as getEntityWrites, cW as gsi, cX as isColumn, cY as isCommandModelContract, cZ as isCommandPlan, c_ as isContractComposeNode, c$ as isContractFromRef, d0 as isContractKeyFieldRef, d1 as isContractKeyRef, d2 as isContractParamRef, d3 as isEntityWritesDefinition, d4 as isKeySegment, d5 as isLifecycleContract, d6 as isMutationFragment, d7 as isMutationInputRef, d8 as isParam, d9 as isPlannedCommandMethod, da as isQueryModelContract, db as isRetryableError, dc as isRetryableTransactionCancellation, dd as k, de as key, df as lifecyclePhaseForIntent, dg as mintContractKeyFieldRef, dh as mintContractParamRef, di as mutation, dj as param, dk as publicCommandModel, dl as publicQueryModel, dm as query, dn as resolveLifecycle, dp as wholeKeysSentinel } from './types--tdHK3vi.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, 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 ViewDefinition, _ as ProjectionDefinition, $ as RelationMetadata, a0 as TransactionItemSpec, a1 as MaintainEffect, M as ModelStatic, f as DDBModel, a2 as Param, a3 as ParamDescriptor, a4 as DefinitionMap, a5 as OperationDefinition, a6 as WriteDefinitionOptions, a7 as PartialQueryKeyOf, a8 as StrictSelectSpec, a9 as EntityInput, aa as UniqueQueryKeyOf, ab as EntityRef, ac as ConditionInput, ad as QueryModelContract, ae as QueryMethodSpec, af as CommandModelContract, ag as CommandMethodSpec, ah as ContractSpec, ai as QuerySpec, aj as CommandSpec, ak as ContextSpec, al as OperationsDocument, am as AnyOperationDefinition, an as BridgeBundle, ao as ConditionSpec } from './types-DuJ08bgc.js';
+export { ap as AggregateMetadata, aq as BatchDeleteRequest, ar as BatchGetOptions, as as BatchGetRequest, at as BatchGetResult, au as BatchPutRequest, av as BatchResult, aw as BatchWriteRequest, ax as CONTRACT_RANGE_FANOUT_CONCURRENCY, ay as CdcMode, az as Change, aA as ChangeBatch, aB as ChangeEventName, aC as ClockMode, aD as CollectionEffect, aE as CollectionOptions, aF as Column, aG as ColumnMap, aH as CommandContractMethodSpec, aI as CommandInputShape, aJ as CommandMethod, aK as CommandPlan, aL as CommandResolutionTarget, aM as CommandResultKind, aN as CommandSelectShape, aO as CompiledFragment, aP as ComposeSpec, aQ as CondSlot, aR as ConditionCheckInput, aS as Connection, aT as ContractCallSignature, aU as ContractCardinality, aV as ContractCommandParams, aW as ContractCommandResult, aX as ContractComposeNode, aY as ContractFromRef, aZ as ContractInputArity, a_ as ContractItem, a$ as ContractKeyFieldRef, b0 as ContractKeyInput, b1 as ContractKeyRef, b2 as ContractKeySpec, b3 as ContractKind, b4 as ContractMethodOp, b5 as ContractParamRef, b6 as ContractQueryParams, b7 as ContractResolution, b8 as CounterAggregate, b9 as CounterEffect, ba as CtxBase, bb as DEFAULT_MAX_ATTEMPTS, bc as DEFAULT_RETRY_POLICY, bd as DeleteOptions, be as DeriveEffect, bf as DerivedEdgeWrite, bg as DerivedUpdate, bh as DescriptorBinding, bi as ENTITY_WRITES_MARKER, bj as EdgeEffect, bk as EffectPath, bl as EmbeddedMetadata, bm as EmitEffect, bn as EntityWritesDefinition, bo as EntityWritesShape, bp as ExecutableCommandContract, bq as ExecutableQueryContract, br as FilterInput, bs as FilterSpec, bt as FragmentInput, bu as GsiDefinitionMarker, bv as GsiOptions, bw as IdempotencyEffect, bx as InProcessWriteDescriptor, by as InputArity, bz as KeyDefinitionMarker, bA as KeySegment, bB as KeySlot, bC as KeyStructure, bD as KeyedResult, bE as LIFECYCLE_CONTRACT_MARKER, bF as LifecycleContract, bG as LifecycleEffects, bH as LiteralParam, bI as MaintainConsistency, bJ as MaintainEvent, bK as MaintainItem, bL as MaintainTrigger, bM as MaintainUpdateMode, bN as MaintenanceGraph, bO as ManifestEntity, bP as ManifestField, bQ as ManifestFieldType, bR as ManifestGsi, bS as ManifestKey, bT as ManifestRelation, bU as ManifestTable, bV as MembershipEffect, bW as MembershipPredicate, bX as MembershipPredicateOp, bY as ModelRef, bZ as MutateMode, b_ as MutateOptions, b$ as MutateParallelResult, c0 as MutateTransactionResult, c1 as MutationBody, c2 as MutationDescriptorMap, c3 as MutationFragment, c4 as MutationInputProxy, c5 as MutationInputRef, c6 as MutationIntent, c7 as NumberParam, c8 as OperationKind, c9 as OperationSpec, ca as ParallelOpResult, cb as ParamKind, cc as ParamSpec, cd as ParamStructure, ce as PersistCtx, cf as PersistOrigin, cg as PlannedCommandMethod, ch as ProjectionDefinitionInput, ci as ProjectionDefinitionMap, cj as ProjectionMap, ck as ProjectionTransform, cl as ProjectionTransformOp, cm as ProjectionVia, cn as PutOptions, co as QueryContractMethodSpec, cp as QueryEnvelopeResult, cq as QueryKeyOf, cr as QueryMethod, cs as QueryResult, ct as RangeConditionSpec, cu as ReadEnvelope, cv as ReadOpCtx, cw as ReadOpKind, cx as ReadOperationType, cy as ReadRouteDescriptor, cz as ReadRouteOptions, cA as ReadRouteResult, cB as RecordedCompose, cC as RelationBuilder, cD as RelationConsistency, cE as RelationLimitOptions, cF as RelationPattern, cG as RelationProjection, cH as RelationReadOptions, cI as RelationSelect, cJ as RelationSpec, cK as RelationUpdateMode, cL as RelationWriteOptions, cM as RequiresEffect, cN as Resolution, cO as RetryInfo, cP as RetryOperationKind, cQ as SPEC_VERSION, cR as SegmentSpec, cS as SegmentedKey, cT as SelectBuilder, cU as SelectOf, cV as SnapshotEffect, cW as StartingPosition, cX as StreamViewType, cY as StringParam, cZ as TransactionContext, c_ as TransactionItemType, c$ as UniqueEffect, d0 as Updatable, d1 as UpdateOptions, d2 as VersionedDefinition, d3 as VersionedDefinitionInput, d4 as ViewDefinitionInput, d5 as ViewDefinitionMap, d6 as ViewRegistry, d7 as ViewSource, d8 as ViewSourceSlice, d9 as WhenSpec, da as WriteCtx, db as WriteDescriptor, dc as WriteEnvelope, dd as WriteInput, de as WriteKind, df as WriteLifecyclePhase, dg as WriteMiddleware, dh as WriteOperationType, di as WriteRecorder, dj as WriteResultProjection, dk as attachModelClass, dl as buildDeleteInput, dm as buildMaintenanceGraph, dn as buildPutInput, dp as buildUpdateInput, dq as compileFragment, dr as compileMutationPlan, ds as compileSingleFragmentPlan, dt as cond, du as contractOfMethodSpec, dv as definePlan, dw as defineProjection, dx as defineProjections, dy as defineVersioned, dz as defineView, dA as defineViews, dB as entityWrites, dC as executeBatchGet, dD as executeBatchWrite, dE as executeCommandMethod, dF as executeDelete, dG as executeKeyedBatchGet, dH as executePut, dI as executeQueryMethod, dJ as executeRangeFanout, dK as executeTransaction, dL as executeUpdate, dM as from, dN as getEntityWrites, dO as gsi, dP as identity, dQ as isColumn, dR as isCommandModelContract, dS as isCommandPlan, dT as isContractComposeNode, dU as isContractFromRef, dV as isContractKeyFieldRef, dW as isContractKeyRef, dX as isContractParamRef, dY as isEntityWritesDefinition, dZ as isKeySegment, d_ as isLifecycleContract, d$ as isMaintainTrigger, e0 as isMutationFragment, e1 as isMutationInputRef, e2 as isParam, e3 as isPlannedCommandMethod, e4 as isProjectionDefinition, e5 as isQueryModelContract, e6 as isRetryableError, e7 as isRetryableTransactionCancellation, e8 as isViewDefinition, e9 as k, ea as key, eb as lifecyclePhaseForIntent, ec as maintainTrigger, ed as mintContractKeyFieldRef, ee as mintContractParamRef, ef as mutation, eg as param, eh as preview, ei as publicCommandModel, ej as publicQueryModel, ek as query, el as resolveLifecycle, em as whenMember, en as wholeKeysSentinel } from './types-DuJ08bgc.js';
 import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
 import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
 
@@ -34,7 +34,7 @@ type ListOptions<T, S extends SelectableOf<T> = SelectableOf<T>> = {
 
 /**
  * Read-middleware runtime (issue #138). Drives the registered {@link Middleware}
- * list through the read hook points R1–R5 with the ordering the proposal
+ * list through the read hook points R1–R5 with the ordering docs/middleware.md
  * specifies:
  *
  * - `before*` (R1 / R2) run **first-registered-first** (FIFO);
@@ -52,7 +52,7 @@ type ListOptions<T, S extends SelectableOf<T> = SelectableOf<T>> = {
  * set stable even if middleware is (un)registered mid-flight, and is
  * concurrency-safe under parallel fan-out (#31).
  *
- * @see docs/proposals/read-middleware.md
+ * @see docs/middleware.md
  */
 
 /**
@@ -313,71 +313,6 @@ interface RelationExecutionPlan {
     readonly resultPaths: readonly string[];
 }
 
-type DynamoType = 'S' | 'N' | 'BOOL' | 'B' | 'SS' | 'NS' | 'L' | 'M';
-interface FieldOptions {
-    format?: 'datetime' | 'date';
-    readonly?: boolean;
-    serialize?: (value: unknown) => unknown;
-    deserialize?: (value: unknown) => unknown;
-}
-interface FieldMetadata {
-    propertyName: string;
-    dynamoType: DynamoType;
-    options?: FieldOptions;
-    /**
-     * For a `@literal(...)` field — a `string`-stored field whose value is one of a
-     * known, finite set — the allowed literal values, in declaration order (issue
-     * #75). Recorded purely as model metadata so a Contract param bound into the
-     * field can recover the precise `literal` param-kind from its bind position
-     * (`src/spec/contracts.ts`), serializing as `{ type: 'literal', literals: [...] }`
-     * instead of the imprecise `'string'`. JSON-safe by construction (a non-empty
-     * array of strings). `undefined` for every other field decorator (`@string`,
-     * `@number`, …), so plain fields are byte-for-byte unchanged (backward compat).
-     */
-    literals?: readonly string[];
-}
-
-interface KeyDefinition {
-    /** The canonical structured key (PK/SK segment lists). */
-    segmented: SegmentedKey;
-    inputFieldNames: string[];
-}
-interface GsiDefinition {
-    indexName: string;
-    /** The canonical structured key (PK/SK segment lists). */
-    segmented: SegmentedKey;
-    inputFieldNames: string[];
-    unique: boolean;
-}
-interface RelationLimitOptions {
-    default: number;
-    max: number;
-}
-interface RelationOptions {
-    limit?: RelationLimitOptions;
-    order?: 'ASC' | 'DESC';
-}
-interface RelationMetadata {
-    type: 'hasMany' | 'hasOne' | 'belongsTo';
-    propertyName: string;
-    targetFactory: () => new (...args: unknown[]) => unknown;
-    keyBinding: Record<string, string>;
-    options?: RelationOptions;
-}
-interface EmbeddedMetadata {
-    propertyName: string;
-    modelFactory: () => new (...args: unknown[]) => unknown;
-}
-interface EntityMetadata {
-    tableName: string;
-    prefix: string;
-    fields: FieldMetadata[];
-    primaryKey: KeyDefinition | null;
-    gsiDefinitions: GsiDefinition[];
-    relations: RelationMetadata[];
-    embeddedFields: EmbeddedMetadata[];
-}
-
 interface LintRule {
     id: string;
     severity: 'error' | 'warning';
@@ -401,6 +336,22 @@ declare class Linter {
 declare class MetadataRegistry {
     private static store;
     private static _linter;
+    /**
+     * A monotonically-increasing counter bumped on every change to the set of
+     * registered models ({@link register} / {@link clear}). It lets a consumer that
+     * caches a structure derived from the whole registry (e.g. the maintenance graph
+     * in `src/spec/mutation-command.ts`) detect that the registry has changed since
+     * the cache was built and rebuild — closing the silent-drop window where a model
+     * registered after a cache build would be invisible to it. Only the membership
+     * of {@link store} changes here; per-model lazy finalize ({@link finalize}) does
+     * not bump it (it adds no relations/triggers, so it cannot change the graph).
+     */
+    private static _generation;
+    /**
+     * The current registry generation (see {@link _generation}). A consumer caches
+     * the value it built against and rebuilds when it no longer matches.
+     */
+    static get generation(): number;
     static register(target: Function, metadata: EntityMetadata): void;
     static get(target: Function): EntityMetadata;
     static has(target: Function): boolean;
@@ -531,9 +482,92 @@ 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;
-declare function belongsTo(targetFactory: () => new (...args: unknown[]) => unknown, keyBinding: Record<string, string>): (_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;
 
+/**
+ * `@aggregate` — a **scalar-aggregate** field decorator (Epic #118 §5.2 counter /
+ * latest preset; issue #122).
+ *
+ * Where `@hasMany` / `@belongsTo` declare a *navigation* (a relation yielding
+ * model instances) and `@string` / `@number` declare a *stored* attribute,
+ * `@aggregate` declares a **scalar value derived by aggregating a source
+ * entity's rows**. It is a field (the decorated property holds a `number` /
+ * `string`), but — like a relation — it carries a source `targetFactory` +
+ * `keyBinding` selecting the rows it aggregates. The declaration surface mirrors
+ * the RFC §5.2 example:
+ *
+ * ```ts
+ * @model({ table: 'AppTable', prefix: 'THREAD' })
+ * class ThreadSummaryModel extends DDBModel {
+ *   @string threadId!: string;
+ *
+ *   @aggregate(() => PostModel, { threadId: 'threadId' }, {
+ *     pattern: 'counter', value: count(),
+ *     write: { maintainedOn: ['Post.created', 'Post.removed'] },
+ *   })
+ *   postCount!: number;
+ *
+ *   @aggregate(() => PostModel, { threadId: 'threadId' }, {
+ *     pattern: 'counter', value: max('createdAt'),
+ *     write: { maintainedOn: ['Post.created'] },
+ *   })
+ *   lastPostAt!: string;
+ * }
+ * ```
+ *
+ * ## Scope (issue #122)
+ *
+ * This is the **declaration surface only** — the decorator records an
+ * {@link AggregateMetadata} into its own collector array (drained by `@model`
+ * into `EntityMetadata.aggregates`), exactly as the relation decorators push to
+ * the relation collector. The aggregation *effect* (maintenance graph #124,
+ * compile injection #125, runtime #127) is out of scope and consumes this
+ * metadata later.
+ *
+ * ## Vocabulary reuse (no double definition)
+ *
+ * `options.pattern` is the shared {@link RelationPattern} (typically `'counter'`)
+ * and `options.write` is the shared {@link RelationWriteOptions} — `maintainedOn`
+ * triggers on the `created|updated|removed` event vocabulary plus
+ * `consistency` (`transactional|eventual`) / `updateMode` (`mutation|stream`).
+ * Both were defined by B (#121) in `src/metadata/types.ts` and are **reused**
+ * here, never re-defined.
+ *
+ * @param targetFactory - Resolves the source entity whose rows are aggregated
+ *   (lazy, mirroring the relation decorators, to tolerate circular imports).
+ * @param keyBinding - The key binding selecting the source rows
+ *   (target key field → source field).
+ * @param options - The aggregate preset / value / maintenance-write declaration.
+ */
+declare function aggregate(targetFactory: () => new (...args: unknown[]) => unknown, keyBinding: Record<string, string>, options: AggregateOptions): (_value: undefined, context: ClassFieldDecoratorContext) => void;
+/**
+ * Value helper for an `@aggregate` field: the **count** aggregation — the
+ * cardinality of source rows matched by the key binding (Epic #118 §5.2
+ * `counter` preset, `count()`). It takes no source field (it counts rows, not a
+ * value), so the decorated field is a `number` (e.g. `postCount!: number`).
+ *
+ * Produces the {@link AggregateValue} IR node `{ op: 'count' }`. This is the
+ * standalone, recorder-free authoring helper used directly in the decorator
+ * argument (mirroring the standalone `preview(...)` / `identity(...)` projection
+ * helpers A (#120) exposes for relation options).
+ */
+declare function count(): AggregateValue;
+/**
+ * Value helper for an `@aggregate` field: the **max** aggregation — the maximum
+ * value of a named source `field` across the rows matched by the key binding
+ * (Epic #118 §5.2 `counter` / latest preset, `max('createdAt')`). The decorated
+ * field's type matches the source field's (e.g. `lastPostAt!: string` ←
+ * `max('createdAt')`).
+ *
+ * Produces the {@link AggregateValue} IR node `{ op: 'max', field }`.
+ *
+ * @param field - The source field whose maximum is tracked (e.g. `'createdAt'`).
+ * @throws if `field` is not a non-empty string (an aggregation over no source
+ *   field is meaningless — a defensive runtime check mirroring `@literal`'s).
+ */
+declare function max(field: string): AggregateValue;
+
 declare class TableMapping {
     private static mapping;
     static set(mapping: Record<string, string>): void;
@@ -1041,6 +1075,246 @@ 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;
+
+/**
+ * External-projection **sink drain** (issue #132) — the asynchronous runtime for
+ * `defineProjection` (`externalProjection`, Epic #118 §5.3 / RFC §4.A.8).
+ *
+ * A `defineProjection` declares a stream + idempotency projection of a source
+ * entity into an EXTERNAL sink (BigQuery / S3 / OpenSearch / Neptune in
+ * production). The transport is the CDC stream: the source entity's writes surface
+ * as {@link ChangeEvent}s (real DynamoDB Streams in production, the
+ * {@link import('./emulator.js').CdcEmulator} in dev/test), and THIS consumer
+ * projects each event's source image and upserts it into the sink.
+ *
+ * ## At-least-once → exactly-once-effect via the idempotency key
+ *
+ * The CDC substrate delivers at-least-once (a single source event may be delivered
+ * more than once). An external sink upsert is the ONE place a duplicate would
+ * double-write, so the projection folds redelivery by the declared
+ * `idempotencyKey` (a source attribute, e.g. `resultId`): the sink is an UPSERT
+ * keyed by that value, so re-delivering the same source event overwrites the same
+ * sink record rather than appending a second. This is the standard "make
+ * at-least-once idempotent with a business key" pattern; the sink need only
+ * support an idempotent put keyed by the idempotency key.
+ *
+ * ## The sink abstraction (dev/test vs production)
+ *
+ * {@link ProjectionSink} is the minimal contract a real sink adapter implements
+ * (`upsert(key, record)` / `delete(key)`). Production wires a BigQuery / S3 /
+ * OpenSearch adapter; dev/test uses {@link InMemoryProjectionSink}, an in-process
+ * map that the integration tests assert convergence + idempotency against. The
+ * drain itself is sink-agnostic — it resolves the projection, computes the key,
+ * and calls the adapter.
+ */
+
+/**
+ * The minimal contract a projection sink adapter implements. An upsert is keyed by
+ * the idempotency key (so a redelivery overwrites the same record), a delete
+ * removes it (for a source `removed` event projected to the sink).
+ */
+interface ProjectionSink {
+    /** Upsert the projected record under the idempotency key (idempotent). */
+    upsert(key: string, record: Record<string, unknown>): void | Promise<void>;
+    /** Remove the record under the idempotency key (for a projected `removed`). */
+    delete?(key: string): void | Promise<void>;
+}
+/**
+ * An in-process {@link ProjectionSink} for dev/test — a map keyed by the
+ * idempotency key. Mirrors what a real sink (BigQuery / S3) does logically: an
+ * upsert keyed by a business key folds at-least-once redelivery to one record. The
+ * integration tests assert convergence + idempotency against {@link records}.
+ */
+declare class InMemoryProjectionSink implements ProjectionSink {
+    /** The current sink contents, keyed by the idempotency key. */
+    readonly records: Map<string, Record<string, unknown>>;
+    /** Total upsert CALLS (including redelivered ones) — distinguishes calls from records. */
+    private upserts;
+    upsert(key: string, record: Record<string, unknown>): void;
+    delete(key: string): void;
+    /** The number of distinct sink records (the converged projection size). */
+    size(): number;
+    /** The total upsert calls (≥ size when redelivery occurred). */
+    upsertCount(): number;
+    /** Reset the sink (test). */
+    reset(): void;
+}
+/** Options for {@link createProjectionSinkDrain}. */
+interface ProjectionSinkDrainOptions {
+    /** The {@link ProjectionDefinition}s (`defineProjection`) this drain applies. */
+    readonly projections: readonly ProjectionDefinition[];
+    /** The external sink adapter the projected records are upserted into. */
+    readonly sink: ProjectionSink;
+}
+/**
+ * A projection sink drain (issue #132): a CDC consumer ({@link ChangeHandler}) that
+ * projects each source event into the external sink, folding at-least-once delivery
+ * by the projection's idempotency key. Construct via
+ * {@link createProjectionSinkDrain}, then subscribe its {@link handler} to a
+ * {@link import('./emulator.js').CdcEmulator} (dev/test) or a real Streams Lambda.
+ */
+declare class ProjectionSinkDrain {
+    private readonly sink;
+    /** Source-entity CLASS name (the `event.model` the capture seam records) → projections. */
+    private readonly bySource;
+    /** Per-(shard,seq) de-dup within one handler invocation (at-least-once). */
+    private applied;
+    constructor(opts: ProjectionSinkDrainOptions);
+    /** The CDC {@link ChangeHandler} to subscribe to an emulator / Streams source. */
+    readonly handler: ChangeHandler;
+    /** Project one source event into the sink for every matching projection. */
+    private applyOne;
+    /** Clear the per-delivery de-dup set (test reset). */
+    reset(): void;
+}
+/** Create a {@link ProjectionSinkDrain} (issue #132). */
+declare function createProjectionSinkDrain(opts: ProjectionSinkDrainOptions): ProjectionSinkDrain;
+/**
+ * Create just the CDC {@link ChangeHandler} for a projection sink drain — the form
+ * to subscribe to an emulator or wire into a production Streams Lambda.
+ */
+declare function createProjectionSinkHandler(opts: ProjectionSinkDrainOptions): ChangeHandler;
+
 /**
  * Per-key cursor envelope for batched `range` (`list`) contract methods (issue
  * #62, CQRS single-service runtime; spec `docs/cqrs-contract.md`,
@@ -1125,10 +1399,14 @@ declare function decodePerKeyCursor(cursor: string, expectedKey: Record<string,
 /**
  * Creates a Linter pre-loaded with rules safe for Entity registration.
  *
- * Rules included: no-scan, require-limit, gsi-ambiguity, missing-gsi, relation-depth.
- * query-boundary is excluded because it flags non-unique GSIs which
- * are valid for list() operations; boundary enforcement is handled
- * at runtime by the planner's boundary-check.
+ * Rules included: no-scan, require-limit, gsi-ambiguity, missing-gsi,
+ * relation-depth, same-partition-preset, plus the Epic #118 Phase 1 maintenance
+ * validators (issue #126): missing-context, 400kb, hot-partition, fan-out,
+ * multi-maintainer-same-row. The maintenance validators are no-ops for any
+ * relation that does not declare `write.maintainedOn`, so unannotated models are
+ * unaffected. query-boundary is excluded because it flags non-unique GSIs which
+ * are valid for list() operations; boundary enforcement is handled at runtime by
+ * the planner's boundary-check.
  */
 declare function createDefaultLinter(): Linter;
 
@@ -1302,12 +1580,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
@@ -1348,6 +1656,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
@@ -1419,6 +1755,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).
  *
@@ -2290,4 +2802,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 { 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, type DynamoType, EDGE_WRITES_MARKER, type EdgeLifecycle, type EdgeWriteDeclaration, type EdgeWriteRecorder, type EdgeWritesDefinition, type EmbeddedMetadata, type EntityMetadata, EntityRef, EventLog, ExecutionPlan, Executor, ExecutorResult, type ExplainInput, FaultSpec, type FieldMetadata, type FieldOptions, type FilterExpressionResult, type GsiDefinition, Item, type 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, type RelationLimitOptions, type RelationMetadata, type RelationOptions, type RelationTraversalOptions, ReplayOptions, RequestContext, ResolvedKey, RetryOverride, RetryPolicy, RetryingExecutor, SegmentedKey, 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, assertBundleSerializable, assertContractBoundaries, assertContractN1Safe, assertJsonSerializable, assertSupportedCondition, belongsTo, binary, boolean, buildBridgeBundle, buildConditionExpression, buildContexts, buildContracts, buildManifest, buildOperations, buildProjection, buildQuerySpec, buildTransactionSpec, buildTransactions, buildUpdateExpression, collectContractBoundaryViolations, collectContractN1Violations, compileFilterExpression, 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, 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, InMemoryProjectionSink, Item, KeyDefinition, type LintResult, type LintRule, Linter, type ListInput, type ListOptions, MAINT_OUTBOX_PK_PREFIX, MAX_TRANSACT_ITEMS, MaintainEffect, MaintenanceDrain, type MaintenanceDrainOptions, type MaintenanceRebuildOptions, MaintenanceRebuilder, Manifest, MetadataRegistry, Middleware, type ModelOptions, ModelStatic, OLD_VALUE_NAMESPACE, OperationDefinition, OperationsDocument, Param, ParamDescriptor, type Parameterize, PartialQueryKeyOf, type PerKeyCursorEnvelope, type PlanInput, PrimaryKeyOf, ProjectionDefinition, type ProjectionResult, type ProjectionSink, ProjectionSinkDrain, type ProjectionSinkDrainOptions, 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, 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, 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, createProjectionSinkDrain, createProjectionSinkHandler, 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 };