graphddb 0.2.5 → 0.3.0

package/dist/{chunk-ITHQ2EDH.js → chunk-QQNP43JL.js}

@@ -1,7 +1,7 @@
 import {
   ChangeCaptureRegistry,
   resolveModelClass
-} from "./chunk-4TYK3AV6.js";
+} from "./chunk-6AIAHP3A.js";
 
 // src/cdc/prng.ts
 var SeededRandom = class {

package/dist/cli.js

@@ -2,10 +2,10 @@
 import {
   buildBridgeBundle,
   normalizeSelectSpec
-} from "./chunk-SGYBE2OV.js";
+} from "./chunk-QEOFIXTN.js";
 import {
   MetadataRegistry
-} from "./chunk-4TYK3AV6.js";
+} from "./chunk-6AIAHP3A.js";
 
 // src/cli.ts
 import { createRequire } from "module";

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 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 { 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;
@@ -1125,10 +1159,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;
 
@@ -2290,4 +2328,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, 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 };

package/dist/index.js

@@ -16,6 +16,7 @@ import {
   buildBridgeBundle,
   buildContexts,
   buildContracts,
+  buildMaintenanceGraph,
   buildManifest,
   buildOperations,
   buildProjection,
@@ -56,6 +57,7 @@ import {
   getEntityWrites,
   getImplicitKeyFields,
   hydrate,
+  identity,
   isCommandModelContract,
   isCommandPlan,
   isContractComposeNode,
@@ -66,6 +68,7 @@ import {
   isEdgeWritesDefinition,
   isEntityWritesDefinition,
   isLifecycleContract,
+  isMaintainTrigger,
   isMutationFragment,
   isMutationInputRef,
   isPlannedCommandMethod,
@@ -73,11 +76,13 @@ import {
   isSelectBuilder,
   isTransactionRef,
   lifecyclePhaseForIntent,
+  maintainTrigger,
   mapWithConcurrency,
   mintContractKeyFieldRef,
   mintContractParamRef,
   mutation,
   plan,
+  preview,
   publicCommandModel,
   publicQueryModel,
   query,
@@ -86,11 +91,11 @@ import {
   validateDepth,
   when,
   wholeKeysSentinel
-} from "./chunk-SGYBE2OV.js";
+} from "./chunk-QEOFIXTN.js";
 import {
   CdcEmulator,
   createCdcEmulator
-} from "./chunk-ITHQ2EDH.js";
+} from "./chunk-QQNP43JL.js";
 import {
   BATCH_GET_MAX_KEYS,
   BATCH_WRITE_MAX_ITEMS,
@@ -139,7 +144,7 @@ import {
   resolveKey,
   resolveModelClass,
   serializeFieldValue
-} from "./chunk-4TYK3AV6.js";
+} from "./chunk-6AIAHP3A.js";
 
 // src/metadata/prefix.ts
 function derivePrefix(customPrefix, className) {
@@ -189,6 +194,7 @@ function validateGsiAmbiguity(primaryKey, gsiDefinitions) {
 var pendingFields = [];
 var pendingEmbedded = [];
 var pendingRelations = [];
+var pendingAggregates = [];
 function collectField(field2) {
   pendingFields.push(field2);
 }
@@ -198,6 +204,9 @@ function collectEmbedded(embedded2) {
 function collectRelation(relation) {
   pendingRelations.push(relation);
 }
+function collectAggregate(aggregate2) {
+  pendingAggregates.push(aggregate2);
+}
 function drainFields() {
   const result = pendingFields;
   pendingFields = [];
@@ -213,6 +222,11 @@ function drainRelations() {
   pendingRelations = [];
   return result;
 }
+function drainAggregates() {
+  const result = pendingAggregates;
+  pendingAggregates = [];
+  return result;
+}
 
 // src/decorators/model.ts
 function model(options) {
@@ -220,6 +234,7 @@ function model(options) {
     const fields = drainFields();
     const embeddedFields = drainEmbedded();
     const relations = drainRelations();
+    const aggregates = drainAggregates();
     const prefix = derivePrefix(options.prefix, context.name);
     MetadataRegistry.register(target, {
       tableName: options.table,
@@ -228,6 +243,7 @@ function model(options) {
       primaryKey: null,
       gsiDefinitions: [],
       relations,
+      aggregates,
       embeddedFields
     });
   };
@@ -322,7 +338,7 @@ function hasMany(targetFactory, keyBinding, options) {
     });
   };
 }
-function belongsTo(targetFactory, keyBinding) {
+function belongsTo(targetFactory, keyBinding, options) {
   return function(_value, context) {
     const propertyName = String(context.name);
     assertRelationPropertyNameAllowed(propertyName);
@@ -330,7 +346,8 @@ function belongsTo(targetFactory, keyBinding) {
       type: "belongsTo",
       propertyName,
       targetFactory,
-      keyBinding
+      keyBinding,
+      options
     });
   };
 }
@@ -347,6 +364,29 @@ function hasOne(targetFactory, keyBinding) {
   };
 }
 
+// src/decorators/aggregate.ts
+function aggregate(targetFactory, keyBinding, options) {
+  return function(_value, context) {
+    collectAggregate({
+      propertyName: String(context.name),
+      targetFactory,
+      keyBinding,
+      options
+    });
+  };
+}
+function count() {
+  return { op: "count" };
+}
+function max(field2) {
+  if (typeof field2 !== "string" || field2.length === 0) {
+    throw new Error(
+      `max(...) requires a non-empty source field name to aggregate (e.g. max('createdAt')), but received ${JSON.stringify(field2)}.`
+    );
+  }
+  return { op: "max", field: field2 };
+}
+
 // src/operations/declarative-transaction.ts
 var PLACEHOLDER_RE = /\{[^{}]+\}/g;
 function resolveTemplate(template, params, element) {
@@ -484,6 +524,79 @@ function entityByName(manifest, name) {
 function physicalTableName(manifest, logical) {
   return manifest.tables[logical]?.physicalName ?? logical;
 }
+function applyMaintainTransform(op, args, value) {
+  if (op === "identity") return value;
+  if (op === "preview") {
+    const n = args[0];
+    if (typeof n !== "number" || !Number.isInteger(n) || n <= 0) {
+      throw new Error(
+        `declarative transaction: a maintenance \`preview\` projection has a non-positive-integer length bound (${JSON.stringify(n)}).`
+      );
+    }
+    if (value === null || value === void 0) return value;
+    return String(value).slice(0, n);
+  }
+  throw new Error(
+    `declarative transaction: unknown maintenance projection op '${String(op)}' (expected 'identity' / 'preview').`
+  );
+}
+function buildMaintainProjection(maintain, params, element) {
+  const out = {};
+  for (const [attr, transform] of Object.entries(maintain.projection)) {
+    const value = resolveValue(`{${transform.inputField}}`, params, element);
+    out[attr] = applyMaintainTransform(transform.op, transform.args, value);
+  }
+  return out;
+}
+function buildMaintainUpdateItem(spec, maintain, table, key2, params, element) {
+  const update = { TableName: table, Key: key2 };
+  if (maintain.kind === "counter") {
+    const counter = maintain.counter;
+    if (counter === void 0) {
+      throw new Error(
+        `declarative transaction: a 'counter' maintenance write on '${spec.entity}' has no \`counter\` payload.`
+      );
+    }
+    update.UpdateExpression = "ADD #a0 :a0";
+    update.ExpressionAttributeNames = { "#a0": counter.attribute };
+    update.ExpressionAttributeValues = {
+      ":a0": typeof counter.delta === "string" ? Number(counter.delta) : counter.delta
+    };
+    return { Update: update };
+  }
+  const projection = buildMaintainProjection(maintain, params, element);
+  if (maintain.kind === "collection") {
+    const field2 = maintain.collection?.field;
+    if (field2 === void 0) {
+      throw new Error(
+        `declarative transaction: a 'collection' maintenance write on '${spec.entity}' has no \`collection.field\`.`
+      );
+    }
+    update.UpdateExpression = "SET #c = list_append(if_not_exists(#c, :empty), :item)";
+    update.ExpressionAttributeNames = { "#c": field2 };
+    update.ExpressionAttributeValues = { ":empty": [], ":item": [projection] };
+  } else {
+    const names = {};
+    const values = {};
+    const sets = [];
+    let i = 0;
+    for (const [attr, value] of Object.entries(projection)) {
+      names[`#m${i}`] = attr;
+      values[`:m${i}`] = value;
+      sets.push(`#m${i} = :m${i}`);
+      i++;
+    }
+    if (sets.length === 0) {
+      throw new Error(
+        `declarative transaction: a 'snapshot' maintenance write on '${spec.entity}' has an empty projection.`
+      );
+    }
+    update.UpdateExpression = `SET ${sets.join(", ")}`;
+    update.ExpressionAttributeNames = names;
+    update.ExpressionAttributeValues = values;
+  }
+  return { Update: update };
+}
 function buildTransactItem(spec, manifest, params, element) {
   const literal2 = spec.literalKey === true;
   const entity = literal2 ? void 0 : entityByName(manifest, spec.entity);
@@ -511,6 +624,9 @@ function buildTransactItem(spec, manifest, params, element) {
     applyCondition(spec.condition, check, params, element);
     return { ConditionCheck: check };
   }
+  if (spec.maintain !== void 0) {
+    return buildMaintainUpdateItem(spec, spec.maintain, table, key2, params, element);
+  }
   const changes = resolveRecord(spec.changes, params, element);
   const adds = resolveRecord(spec.add, params, element);
   const names = {};
@@ -600,8 +716,8 @@ async function executeDeclarativeTransaction(spec, manifest, params) {
     expanded.map((e) => e.item),
     {
       modelBySignature,
-      limitError: (count) => new Error(
-        `declarative transaction: expanded to ${count} items, exceeds the DynamoDB TransactWriteItems limit of ${MAX_TRANSACT_ITEMS}.`
+      limitError: (count2) => new Error(
+        `declarative transaction: expanded to ${count2} items, exceeds the DynamoDB TransactWriteItems limit of ${MAX_TRANSACT_ITEMS}.`
       )
     }
   );
@@ -1063,6 +1179,7 @@ export {
   SPEC_VERSION,
   TableMapping,
   TransactionContext,
+  aggregate,
   assertBundleSerializable,
   assertContractBoundaries,
   assertContractN1Safe,
@@ -1077,6 +1194,7 @@ export {
   buildContexts,
   buildContracts,
   buildDeleteInput,
+  buildMaintenanceGraph,
   buildManifest,
   buildOperations,
   buildProjection,
@@ -1094,6 +1212,7 @@ export {
   compileSingleFragmentPlan,
   cond,
   contractOfMethodSpec,
+  count,
   createCdcEmulator,
   createDefaultLinter,
   datetime,
@@ -1146,6 +1265,7 @@ export {
   hasMany,
   hasOne,
   hydrate,
+  identity,
   isColumn,
   isCommandModelContract,
   isCommandPlan,
@@ -1158,6 +1278,7 @@ export {
   isEntityWritesDefinition,
   isKeySegment,
   isLifecycleContract,
+  isMaintainTrigger,
   isMutationFragment,
   isMutationInputRef,
   isParam,
@@ -1172,7 +1293,9 @@ export {
   lifecyclePhaseForIntent,
   list,
   literal,
+  maintainTrigger,
   map,
+  max,
   mintContractKeyFieldRef,
   mintContractParamRef,
   missingGsiRule,
@@ -1183,6 +1306,7 @@ export {
   numberSet,
   param,
   plan,
+  preview,
   publicCommandModel,
   publicQueryModel,
   query,

package/dist/testing/index.d.ts

@@ -1,4 +1,4 @@
-import { E as Executor, D as DynamoDBOperation, R as ReadExecOptions, a as ExecutorResult, B as BatchGetExecInput, P as PutInput, W as WriteExecOptions, b as WriteResult, U as UpdateInput, c as DeleteInput, d as BatchWriteExecItem, e as BatchExecOptions, T as TransactWriteExecItem, M as ModelStatic, f as DDBModel, C as ChangeEvent } from '../types--tdHK3vi.js';
+import { E as Executor, D as DynamoDBOperation, R as ReadExecOptions, a as ExecutorResult, B as BatchGetExecInput, P as PutInput, W as WriteExecOptions, b as WriteResult, U as UpdateInput, c as DeleteInput, d as BatchWriteExecItem, e as BatchExecOptions, T as TransactWriteExecItem, M as ModelStatic, f as DDBModel, C as ChangeEvent } from '../types-xJRn5qkv.js';
 import '@aws-sdk/client-dynamodb';
 
 /**

package/dist/testing/index.js

@@ -1,12 +1,12 @@
 import {
   createCdcEmulator
-} from "../chunk-ITHQ2EDH.js";
+} from "../chunk-QQNP43JL.js";
 import {
   ClientManager,
   MetadataRegistry,
   TableMapping,
   resolveModelClass
-} from "../chunk-4TYK3AV6.js";
+} from "../chunk-6AIAHP3A.js";
 
 // src/memory/memory-store.ts
 function deepClone(value) {