graphddb 0.5.1 → 0.5.3

package/dist/{types-B9rJ1z3H.d.ts → maintenance-view-adapter-D5t9taTE.d.ts}

@@ -1,5 +1,118 @@
 import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
 
+/**
+ * CDC emulator types (issue #72). These types are **cdc-module-owned**; core
+ * never references them. The {@link ChangeEvent} shape mirrors DynamoDB Streams
+ * (`NEW_AND_OLD_IMAGES`) so a consumer written against the emulator runs
+ * unchanged against real Streams in production (spec §4).
+ */
+/** Stream view type. Fixed to `NEW_AND_OLD_IMAGES` — incremental aggregation
+ * needs both images (spec §4). */
+type StreamViewType = 'NEW_AND_OLD_IMAGES';
+/** Stream event kind, matching DynamoDB Streams. */
+type ChangeEventName = 'INSERT' | 'MODIFY' | 'REMOVE';
+/**
+ * A single change event. Within one shard, `sequenceNumber` is monotonically
+ * increasing; across shards order is independent (spec §6).
+ */
+interface ChangeEvent<T = Record<string, unknown>> {
+    eventName: ChangeEventName;
+    table: string;
+    /** Resolved model name when known. */
+    model?: string;
+    keys: {
+        pk: string;
+        sk: string;
+    };
+    /** Present for MODIFY / REMOVE. */
+    oldImage?: T;
+    /** Present for INSERT / MODIFY. */
+    newImage?: T;
+    /** Deterministic-clock-derived creation time (ISO 8601). */
+    approximateCreationTime: string;
+    /** Monotonic within a shard (zero-padded for lexicographic ordering). */
+    sequenceNumber: string;
+    /** Partition = hash(pk). */
+    shardId: string;
+}
+/** A delivered batch. Records of the same shard are in `sequenceNumber` order. */
+interface ChangeBatch<T = Record<string, unknown>> {
+    records: ChangeEvent<T>[];
+}
+/**
+ * The consumer's response to a batch (spec §6, `ReportBatchItemFailures`
+ * equivalent). Returning the `sequenceNumber`s of records that failed lets the
+ * emulator advance the checkpoint past the successful prefix and redeliver only
+ * the failures.
+ */
+interface BatchResult {
+    /** `sequenceNumber`s of records the consumer failed to process. */
+    batchItemFailures?: string[];
+}
+/** The consumer handler. */
+type ChangeHandler = (batch: ChangeBatch) => Promise<BatchResult | void>;
+/** Unsubscribe handle. */
+type Unsubscribe = () => void;
+/** Where a fresh subscriber begins reading. */
+type StartingPosition = 'TRIM_HORIZON' | 'LATEST';
+/** Clock mode. `virtual` makes time deterministic via `advanceClock`. */
+type ClockMode = 'real' | 'virtual';
+/** Delivery mode (spec §7). */
+type CdcMode = 'inline' | 'queued' | 'record' | 'replay';
+/** Deterministic fault-injection spec (spec §8). All probabilities are seeded. */
+interface FaultSpec {
+    /** Probability [0,1] a delivered record is also re-delivered (duplicate). */
+    duplicate?: number;
+    /** Shuffle within-shard order on delivery (invariant-violation testing). */
+    reorder?: boolean;
+    /** Per-record virtual-time delivery delay range (ms). Requires queued mode. */
+    delay?: {
+        min: number;
+        max: number;
+    };
+    /** Probability [0,1] a record is dropped on first delivery then redelivered. */
+    dropThenRedeliver?: number;
+    /** Probability [0,1] a record is reported as a partial-batch failure. */
+    partialBatchFailure?: number;
+}
+/** A reference whose recompute should be forced to race a mark (spec §8, §7). */
+interface ConcurrentRecomputeRef {
+    /** Opaque node ref the harness recomputes concurrently with marking. */
+    ref: string;
+}
+/** A persisted event log (spec §10, record/replay). */
+interface EventLog {
+    seed: number;
+    events: ChangeEvent[];
+}
+/** Replay options (spec §10). */
+interface ReplayOptions {
+    /** Deliver events in a deterministic shuffled order (any-order replay). */
+    shuffle?: boolean;
+    /** Probability [0,1] each event is delivered twice during replay. */
+    duplicate?: number;
+}
+/** Constructor options (spec §11). */
+interface CdcEmulatorOptions {
+    /** Stream-enabled model classes (opt-in; default none). */
+    models?: Function[];
+    /** Delivery mode. Default `inline`. */
+    mode?: CdcMode;
+    /** Clock mode. Default `virtual` for queued, `real` otherwise. */
+    clock?: ClockMode;
+    /** Records per delivered batch. Default 100. */
+    batchSize?: number;
+    /** Max redelivery attempts before a record goes to the DLQ. Default 3. */
+    maxRetries?: number;
+    /** Where a subscriber starts. Default `TRIM_HORIZON`. */
+    startingPosition?: StartingPosition;
+    /** Seed for fault injection / shard assignment determinism. Default 1. */
+    seed?: number;
+    /** Number of shards events are partitioned across. Default 8. */
+    shardCount?: number;
+}
+type ShardId = string;
+
 /**
  * App-level throttle / transient-error retry for single-op sends (issue #111).
  *
@@ -724,11 +837,26 @@ interface GsiDefinitionMarker<T extends Record<string, unknown> = Record<string,
     readonly segmented: SegmentedKey;
     readonly inputFieldNames: string[];
     readonly unique: U;
+    /**
+     * Optional human-readable description of the GSI (issue #166, follow-up of #154),
+     * from `gsi(name, key, { description })`. Pure documentation — the registry copies
+     * it onto {@link GsiDefinition} (→ `manifest.json` + generated Python). Absent
+     * unless declared.
+     */
+    readonly description?: string;
     /** @internal Phantom field for type-level input type extraction. */
     readonly _phantom?: T;
 }
 interface GsiOptions {
     unique?: boolean;
+    /**
+     * Optional human-readable description of the index (issue #166, follow-up of #154).
+     * Pure documentation metadata — it does NOT affect the index key, projection, or any
+     * runtime behaviour. Propagated to `manifest.json` ({@link ManifestGsi.description})
+     * and surfaces as the docstring of a generated Python query method that reads through
+     * this index. Omit for byte-identical output.
+     */
+    description?: string;
 }
 type GsiBuilder<T extends Record<string, unknown>> = (c: {
     readonly [K in keyof T]-?: Column<T[K], T>;
@@ -2817,74 +2945,6 @@ declare function mutation(name: string, body: MutationBody): CommandPlan;
  */
 declare const definePlan: typeof mutation;
 
-/**
- * Decorator-metadata → maintenance-graph `ViewDefinition` adapter (issue #152).
- *
- * ## What this replaces
- *
- * The old `defineView` / `defineVersioned` builders (deleted) registered
- * `ViewDefinition`s into a side `ViewRegistry`, which the maintenance graph read.
- * That builder carried a registration side-effect + a `generation` counter (a
- * silent-drop guard). This adapter removes that whole path: it derives the SAME
- * `ViewDefinition` IR purely from the declarative `MetadataRegistry` — the
- * Contract-layer SSoT, whose own `generation` counter is the single
- * invalidation source — so a view declared via `@model({ kind })` + `@maintainedFrom`
- * (and a versioned relation declared via `@hasOne/@hasMany` `pattern`) is discovered
- * with no separate registry.
- *
- * ## IR invariance
- *
- * The `ViewDefinition` / `ViewSourceSlice` shapes are UNCHANGED. The maintenance
- * graph, the K (#130) stream/drain, and the L (#131) rebuild consume the adapter's
- * output exactly as they consumed `ViewRegistry.getAll()`. Only the SOURCE of the
- * definitions moved from a builder side-effect to declarative metadata.
- *
- * ## Order independence (issue #152 hardening)
- *
- * Stacked `@maintainedFrom` declarations carry no order meaning. The adapter rejects
- * — symmetrically, so the error is identical whichever order the decorators are
- * stacked — any two declarations on the same view that:
- *   1. write the SAME projection target attribute (ambiguous duplicate projection);
- *   2. maintain the SAME `collection.field`;
- *   3. bind the SAME view-key field to a DIFFERENT source path (the view-row identity
- *      would be inconsistent across sources).
- * A legitimate multi-source view (different sources filling DIFFERENT fields, all
- * binding the SAME key the SAME way) is fine.
- */
-
-type AnyModelClass = abstract new (...args: any[]) => any;
-/** The view source slice IR the maintenance graph consumes (one per source × view). */
-interface ViewSourceSlice {
-    readonly sourceClass: AnyModelClass;
-    readonly maintainedOn: readonly MaintainTrigger[];
-    readonly keys: Readonly<Record<string, EffectPath>>;
-    readonly project: ProjectionMap;
-    readonly collection?: {
-        readonly field: string;
-        readonly maxItems?: number;
-        readonly orderBy?: EffectPath;
-        readonly orderDir?: 'ASC' | 'DESC';
-    };
-    readonly predicate?: MembershipPredicate;
-}
-/** The view definition IR — an independent view row maintained from one or more sources. */
-interface ViewDefinition {
-    readonly name: string;
-    readonly viewClass: AnyModelClass;
-    readonly pattern: 'materializedView' | 'sparseView';
-    readonly slices: readonly ViewSourceSlice[];
-    readonly updateMode?: 'mutation' | 'stream';
-    readonly consistency?: 'transactional' | 'eventual';
-}
-/**
- * Build every {@link ViewDefinition} for a registry — from `@model({ kind })` +
- * `@maintainedFrom` view models AND from versioned-pattern relations. This is the
- * adapter the maintenance graph calls in place of the deleted `ViewRegistry.getAll()`.
- *
- * @param registry The models to scan. Defaults to `MetadataRegistry.getAll()`.
- */
-declare function collectViewDefinitions(registry?: ReadonlyMap<Function, EntityMetadata>): ViewDefinition[];
-
 /**
  * Maintenance graph builder (Epic #118 issue #124 — the RFC B-案 core).
  *
@@ -3099,6 +3159,14 @@ interface ManifestKey {
 interface ManifestGsi extends ManifestKey {
     readonly indexName: string;
     readonly unique: boolean;
+    /**
+     * Optional human-readable description of the index (issue #166, follow-up of #154),
+     * from `gsi(name, key, { description })`. Pure documentation — absent unless declared,
+     * so a GSI with no description serializes byte-identically to the pre-#166 manifest.
+     * The Python codegen surfaces it as the docstring of a generated query method that
+     * reads through this index.
+     */
+    readonly description?: string;
 }
 interface ManifestRelation {
     readonly type: 'hasMany' | 'hasOne' | 'belongsTo';
@@ -3106,6 +3174,14 @@ interface ManifestRelation {
     readonly target: string;
     /** target field → source field (on this entity). */
     readonly keyBinding: Readonly<Record<string, string>>;
+    /**
+     * Optional human-readable description of the relation (issue #166, follow-up of
+     * #154), from `@hasMany/@belongsTo/@hasOne(..., { description })`. Pure documentation
+     * — absent unless declared, so a relation with no description serializes
+     * byte-identically to the pre-#166 manifest. The Python codegen surfaces it as a
+     * trailing `# …` comment on the relation's field in the generated result type.
+     */
+    readonly description?: string;
 }
 interface ManifestEntity {
     /** Declared (logical) table name. */
@@ -4069,6 +4145,56 @@ interface DerivedMaintainWrite {
         readonly value?: unknown;
     };
 }
+/**
+ * Drop the cached global {@link MaintenanceGraph} (built lazily by
+ * {@link resolveMaintainers}). Invalidation is now automatic — the cache is keyed
+ * by {@link MetadataRegistry.generation}, so a model registered after a build is
+ * already picked up without calling this. Retained as an explicit escape hatch (and
+ * for source-compatibility); forcing a rebuild is never required for correctness.
+ */
+declare function resetMaintenanceGraphCache(): void;
+/**
+ * Resolve the maintenance {@link MaintainItem effects} a fragment's lifecycle event
+ * fires (issue #125 — the compile-side consumer of D/#124's {@link MaintenanceGraph}).
+ * The fragment's source entity is its written model (its LOGICAL name — #118
+ * contract), and the trigger is `<logicalName>.<event>` where `event` is the
+ * past-tense of the fragment intent ({@link INTENT_MAINTAIN_EVENT}). Returns every
+ * `MaintainItem` the graph indexes under that trigger (`graph.effectsFor(...)`),
+ * empty when nothing maintains on it (the no-regression path — a fragment that fires
+ * no maintainer compiles exactly as before).
+ *
+ * @param fragment The fragment whose lifecycle event is the maintenance trigger.
+ * @param graph    The maintenance graph to query. Defaults to a lazily-built,
+ *   cached graph over the global registry ({@link MetadataRegistry.getAll}); an
+ *   explicit graph is accepted for scoped tests.
+ */
+declare function resolveMaintainers(fragment: MutationFragment, graph?: MaintenanceGraph): readonly MaintainItem[];
+/**
+ * Cross-fragment guard (issue #127 audit 是正1): reject — LOUDLY, with the true cause
+ * named — a set of aggregated maintenance writes (collected across ALL of a multi-
+ * fragment mutation's fragments by {@link buildPlannedCommandMethod}'s flatMap) in
+ * which **two or more** writes resolve to the SAME destination (owner) row.
+ *
+ * ## Why this layer exists
+ *
+ * 論点2 = b ("1 mutation × 1 target row = 1 maintain effect") must hold for the WHOLE
+ * mutation, not just within one fragment. {@link deriveMaintainItems} enforces it
+ * INTRA-fragment, but two *different* fragments can each fire a maintainer onto the
+ * same owner row; the flatMap that aggregates them is a plain concat and would not
+ * notice. Without this guard those two writes collapse together in the runtime's
+ * same-physical-key layer and surface as a `mergeAddUpdates` "ADD delta is non-numeric"
+ * throw — loud (atomicity is preserved) but MISLEADING: it reads as a derived-counter
+ * merge failure and hides the real cause (two maintenance effects resolving to one
+ * owner row). This guard fires FIRST, with a message that names the true cause.
+ *
+ * The identity rule is {@link maintainWriteRowKey} — the same owner-row identity the
+ * intra-fragment reject uses (`destinationRowKey`), so both layers agree on what "the
+ * same row" means. Merging two maintenance writes into one row is a future issue (the
+ * #96 same-physical-key "may not touch one key twice" philosophy); this layer rejects.
+ *
+ * @throws if two aggregated maintenance writes resolve to the same owner row.
+ */
+declare function assertNoCrossFragmentMaintainCollision(methodName: string, writes: readonly DerivedMaintainWrite[]): void;
 /**
  * A **derived uniqueness guard** — the marker-row `Put` (and, on a unique-field
  * change, the old-guard `Delete` + new-guard `Put` swap) that enforces an
@@ -4386,6 +4512,8 @@ declare function compileFragment(fragment: MutationFragment, index?: number, res
  * @throws if `plan` is not a {@link CommandPlan}, or declares more than one fragment.
  */
 declare function compileSingleFragmentPlan(plan: CommandPlan): CompiledFragment;
+/** The DynamoDB `TransactWriteItems` item cap — an atomic tx is never split (#64). */
+declare const MAX_TRANSACT_COMPOSE_ITEMS = 25;
 /**
  * The result of compiling a (1..N)-fragment {@link CommandPlan} (#90): the ordered
  * per-fragment {@link CompiledFragment}s, merged so they form **one atomic
@@ -5992,119 +6120,6 @@ type MutateParallelResult<E extends WriteEnvelope> = {
     readonly [K in keyof E]: BulkWrap<E[K], ParallelResultOf<E[K]>>;
 };
 
-/**
- * CDC emulator types (issue #72). These types are **cdc-module-owned**; core
- * never references them. The {@link ChangeEvent} shape mirrors DynamoDB Streams
- * (`NEW_AND_OLD_IMAGES`) so a consumer written against the emulator runs
- * unchanged against real Streams in production (spec §4).
- */
-/** Stream view type. Fixed to `NEW_AND_OLD_IMAGES` — incremental aggregation
- * needs both images (spec §4). */
-type StreamViewType = 'NEW_AND_OLD_IMAGES';
-/** Stream event kind, matching DynamoDB Streams. */
-type ChangeEventName = 'INSERT' | 'MODIFY' | 'REMOVE';
-/**
- * A single change event. Within one shard, `sequenceNumber` is monotonically
- * increasing; across shards order is independent (spec §6).
- */
-interface ChangeEvent<T = Record<string, unknown>> {
-    eventName: ChangeEventName;
-    table: string;
-    /** Resolved model name when known. */
-    model?: string;
-    keys: {
-        pk: string;
-        sk: string;
-    };
-    /** Present for MODIFY / REMOVE. */
-    oldImage?: T;
-    /** Present for INSERT / MODIFY. */
-    newImage?: T;
-    /** Deterministic-clock-derived creation time (ISO 8601). */
-    approximateCreationTime: string;
-    /** Monotonic within a shard (zero-padded for lexicographic ordering). */
-    sequenceNumber: string;
-    /** Partition = hash(pk). */
-    shardId: string;
-}
-/** A delivered batch. Records of the same shard are in `sequenceNumber` order. */
-interface ChangeBatch<T = Record<string, unknown>> {
-    records: ChangeEvent<T>[];
-}
-/**
- * The consumer's response to a batch (spec §6, `ReportBatchItemFailures`
- * equivalent). Returning the `sequenceNumber`s of records that failed lets the
- * emulator advance the checkpoint past the successful prefix and redeliver only
- * the failures.
- */
-interface BatchResult {
-    /** `sequenceNumber`s of records the consumer failed to process. */
-    batchItemFailures?: string[];
-}
-/** The consumer handler. */
-type ChangeHandler = (batch: ChangeBatch) => Promise<BatchResult | void>;
-/** Unsubscribe handle. */
-type Unsubscribe = () => void;
-/** Where a fresh subscriber begins reading. */
-type StartingPosition = 'TRIM_HORIZON' | 'LATEST';
-/** Clock mode. `virtual` makes time deterministic via `advanceClock`. */
-type ClockMode = 'real' | 'virtual';
-/** Delivery mode (spec §7). */
-type CdcMode = 'inline' | 'queued' | 'record' | 'replay';
-/** Deterministic fault-injection spec (spec §8). All probabilities are seeded. */
-interface FaultSpec {
-    /** Probability [0,1] a delivered record is also re-delivered (duplicate). */
-    duplicate?: number;
-    /** Shuffle within-shard order on delivery (invariant-violation testing). */
-    reorder?: boolean;
-    /** Per-record virtual-time delivery delay range (ms). Requires queued mode. */
-    delay?: {
-        min: number;
-        max: number;
-    };
-    /** Probability [0,1] a record is dropped on first delivery then redelivered. */
-    dropThenRedeliver?: number;
-    /** Probability [0,1] a record is reported as a partial-batch failure. */
-    partialBatchFailure?: number;
-}
-/** A reference whose recompute should be forced to race a mark (spec §8, §7). */
-interface ConcurrentRecomputeRef {
-    /** Opaque node ref the harness recomputes concurrently with marking. */
-    ref: string;
-}
-/** A persisted event log (spec §10, record/replay). */
-interface EventLog {
-    seed: number;
-    events: ChangeEvent[];
-}
-/** Replay options (spec §10). */
-interface ReplayOptions {
-    /** Deliver events in a deterministic shuffled order (any-order replay). */
-    shuffle?: boolean;
-    /** Probability [0,1] each event is delivered twice during replay. */
-    duplicate?: number;
-}
-/** Constructor options (spec §11). */
-interface CdcEmulatorOptions {
-    /** Stream-enabled model classes (opt-in; default none). */
-    models?: Function[];
-    /** Delivery mode. Default `inline`. */
-    mode?: CdcMode;
-    /** Clock mode. Default `virtual` for queued, `real` otherwise. */
-    clock?: ClockMode;
-    /** Records per delivered batch. Default 100. */
-    batchSize?: number;
-    /** Max redelivery attempts before a record goes to the DLQ. Default 3. */
-    maxRetries?: number;
-    /** Where a subscriber starts. Default `TRIM_HORIZON`. */
-    startingPosition?: StartingPosition;
-    /** Seed for fault injection / shard assignment determinism. Default 1. */
-    seed?: number;
-    /** Number of shards events are partitioned across. Default 8. */
-    shardCount?: number;
-}
-type ShardId = string;
-
 /**
  * `subscribe` — the declarative, batch CDC consumer builder (issue #153).
  *
@@ -6525,6 +6540,24 @@ interface MaintainedFromMetadata {
     when?: MembershipPredicate;
     consistency?: MaintainConsistency;
     updateMode?: MaintainUpdateMode;
+    /**
+     * Optional human-readable description of this maintained-from source slice (issue
+     * #166, follow-up of #154), supplied via
+     * `@maintainedFrom(() => Source, (self, source) => ({ description, ... }))`. Pure
+     * documentation metadata — it does NOT affect the maintenance IR (`keyBind` /
+     * `project` / `on` / `collection` / `when`) or any runtime behaviour.
+     *
+     * NOTE (representation): the maintenance IR is deliberately kept OFF the
+     * serializable `manifest.json` / `operations.json` — the {@link Manifest} carries
+     * only the physical shape (table / keys / GSIs / relation navigation), NOT the
+     * maintenance graph (see `detectStreamMaintenance` in `src/codegen/cloudformation.ts`).
+     * There is therefore no manifest / operations / generated-Python site for a
+     * maintained-from source; this description is captured at the metadata layer only
+     * (mirroring where #154 captured its descriptions before propagation), available to
+     * any future consumer that DOES surface `@maintainedFrom` (e.g. the CDC-projection
+     * typed-consumer path, #153). Absent → byte-for-byte unchanged metadata.
+     */
+    description?: string;
 }
 interface KeyDefinition {
     /** The canonical structured key (PK/SK segment lists). */
@@ -6537,6 +6570,17 @@ interface GsiDefinition {
     segmented: SegmentedKey;
     inputFieldNames: string[];
     unique: boolean;
+    /**
+     * Optional human-readable description of the GSI (issue #166, follow-up of #154),
+     * supplied via `gsi(name, key, { description })`. Pure documentation metadata — it
+     * does NOT affect the index key, projection, or any runtime behaviour. When present
+     * it is propagated to the index entry in `manifest.json`
+     * ({@link ManifestGsi.description}) and surfaces as the docstring of any generated
+     * Python query method that reads through this index (a query carrying the GSI's
+     * `indexName`, when the query itself declares no description). Absent →
+     * byte-for-byte unchanged output (backward compatible).
+     */
+    description?: string;
 }
 interface RelationLimitOptions {
     default: number;
@@ -6635,6 +6679,16 @@ type RelationProjection = Readonly<Record<string, ProjectionTransform | string>>
 interface RelationOptions {
     limit?: RelationLimitOptions;
     order?: 'ASC' | 'DESC';
+    /**
+     * Optional human-readable description of the relation (issue #166, follow-up of
+     * #154), supplied via `@hasMany/@belongsTo/@hasOne(() => T, keyBind, { description })`.
+     * Pure documentation metadata — it does NOT affect navigation, key binding, or any
+     * runtime behaviour. When present it is propagated to the relation entry in
+     * `manifest.json` ({@link ManifestRelation.description}) and surfaces as a trailing
+     * `# …` comment on the relation's field in the generated Python result TypedDict /
+     * dataclass. Absent → byte-for-byte unchanged output (backward compatible).
+     */
+    description?: string;
     /**
      * Named maintenance preset (Epic #118). Omitted = plain read-only navigation,
      * fully backward compatible with the historical relation decorators.
@@ -6809,4 +6863,72 @@ interface EntityMetadata {
     ttlAttribute?: string;
 }
 
-export { type FaultSpec as $, type AggregateOptions as A, type BatchGetExecInput as B, type ChangeEvent as C, type DynamoDBOperation as D, type Executor as E, type FieldOptions as F, type GsiDefinition as G, type SelectBuilderSpec as H, type Item as I, type RawCondition as J, type KeyDefinition as K, type TransactionSpec as L, type ModelStatic as M, type Manifest as N, type RetryOverride as O, type PutInput as P, type ExecutionPlan as Q, type ReadExecOptions as R, type SelectableOf as S, type TransactWriteExecItem as T, type UpdateInput as U, type FieldMetadata as V, type WriteExecOptions as W, type ResolvedKey as X, type CdcEmulatorOptions as Y, type ChangeHandler as Z, type Unsubscribe as _, type ExecutorResult as a, type Connection as a$, type ConcurrentRecomputeRef as a0, type EventLog as a1, type ReplayOptions as a2, type ShardId as a3, type ViewDefinition as a4, type RelationMetadata as a5, type TransactionItemSpec as a6, type MaintainEffect as a7, type Param as a8, type ParamDescriptor as a9, BatchGetResult as aA, type BatchPutRequest as aB, type BatchResult as aC, type BatchWriteRequest as aD, CONTRACT_RANGE_FANOUT_CONCURRENCY as aE, type CdcMode as aF, type CdcModelRegistry as aG, type CdcSubscribeHandlers as aH, type Change as aI, type ChangeBatch as aJ, type ChangeEventName as aK, type ClockMode as aL, type CollectionEffect as aM, type CollectionOptions as aN, type Column as aO, type ColumnMap as aP, type CommandContractMethodSpec as aQ, type CommandInputShape as aR, type CommandMethod as aS, type CommandPlan as aT, type CommandResolutionTarget as aU, type CommandResultKind as aV, type CommandSelectShape as aW, type CompiledFragment as aX, type ComposeSpec as aY, type CondSlot as aZ, type ConditionCheckInput as a_, type DefinitionMap as aa, type OperationDefinition as ab, type WriteDefinitionOptions as ac, type PartialQueryKeyOf as ad, type StrictSelectSpec as ae, type ReadDefinitionOptions as af, type EntityInput as ag, type UniqueQueryKeyOf as ah, type EntityRef as ai, type ConditionInput as aj, type QueryModelContract as ak, type QueryMethodSpec as al, type CommandModelContract as am, type CommandMethodSpec as an, type ContractSpec as ao, type QuerySpec as ap, type CommandSpec as aq, type ContextSpec as ar, type OperationsDocument as as, type AnyOperationDefinition as at, type BridgeBundle as au, type ConditionSpec as av, type AggregateMetadata as aw, type BatchDeleteRequest as ax, type BatchGetOptions as ay, type BatchGetRequest as az, type WriteResult as b, type MembershipEffect as b$, type ContractCallSignature as b0, type ContractCardinality as b1, type ContractCommandParams as b2, type ContractCommandResult as b3, type ContractComposeNode as b4, type ContractFromRef as b5, type ContractInputArity as b6, type ContractItem as b7, type ContractKeyFieldRef as b8, type ContractKeyInput as b9, type FilterInput as bA, type FilterSpec as bB, type FragmentInput as bC, type GsiDefinitionMarker as bD, type GsiOptions as bE, type IdempotencyEffect as bF, type InProcessWriteDescriptor as bG, type InputArity as bH, type KeyDefinitionMarker as bI, type KeySegment as bJ, type KeySlot as bK, type KeyStructure as bL, type KeyedResult as bM, LIFECYCLE_CONTRACT_MARKER as bN, type LifecycleContract as bO, type LifecycleEffects as bP, type LiteralParam as bQ, type MaintainItem as bR, type MaintainTrigger as bS, type MaintenanceGraph as bT, type ManifestEntity as bU, type ManifestField as bV, type ManifestFieldType as bW, type ManifestGsi as bX, type ManifestKey as bY, type ManifestRelation as bZ, type ManifestTable as b_, type ContractKeyRef as ba, type ContractKeySpec as bb, type ContractKind as bc, type ContractMethodOp as bd, type ContractParamRef as be, type ContractQueryParams as bf, type ContractResolution as bg, type CounterAggregate as bh, type CounterEffect as bi, type CtxBase as bj, DEFAULT_MAX_ATTEMPTS as bk, DEFAULT_RETRY_POLICY as bl, type DeleteOptions as bm, type DeriveEffect as bn, type DerivedEdgeWrite as bo, type DerivedUpdate as bp, type DescriptorBinding as bq, ENTITY_WRITES_MARKER as br, type EdgeEffect as bs, type EffectPath as bt, type EmbeddedMetadata as bu, type EmitEffect as bv, type EntityWritesDefinition as bw, type EntityWritesShape as bx, type ExecutableCommandContract as by, type ExecutableQueryContract as bz, type DeleteInput as c, TransactionContext as c$, type ModelRef as c0, type MutateMode as c1, type MutateOptions as c2, type MutateParallelResult as c3, type MutateTransactionResult as c4, type MutationBody as c5, type MutationDescriptorMap as c6, type MutationFragment as c7, type MutationInputProxy as c8, type MutationInputRef as c9, type ReadRouteResult as cA, type RecordedCompose as cB, type RelationBuilder as cC, type RelationConsistency as cD, type RelationLimitOptions as cE, type RelationPattern as cF, type RelationProjection as cG, type RelationReadOptions as cH, type RelationSelect as cI, type RelationSpec as cJ, type RelationUpdateMode as cK, type RelationWriteOptions as cL, type RequiresEffect as cM, type Resolution as cN, type RetryInfo as cO, type RetryOperationKind as cP, SPEC_VERSION as cQ, type SegmentSpec as cR, type SegmentedKey as cS, type SelectBuilder as cT, type SelectOf as cU, type SnapshotEffect as cV, type StartingPosition as cW, type StreamViewType as cX, type StringParam as cY, type SubscribeHandler as cZ, type SubscribeHandlers as c_, type MutationIntent as ca, type NumberParam as cb, type OperationKind as cc, type OperationSpec as cd, type ParallelOpResult as ce, type ParamKind as cf, type ParamSpec as cg, type ParamStructure as ch, type PersistCtx as ci, type PersistOrigin as cj, type PlannedCommandMethod as ck, type ProjectionMap as cl, type ProjectionTransformOp as cm, type PutOptions as cn, type QueryContractMethodSpec as co, type QueryEnvelopeResult as cp, type QueryKeyOf as cq, type QueryMethod as cr, type QueryResult as cs, type RangeConditionSpec as ct, type ReadEnvelope as cu, type ReadOpCtx as cv, type ReadOpKind as cw, type ReadOperationType as cx, type ReadRouteDescriptor as cy, type ReadRouteOptions as cz, type BatchWriteExecItem as d, isRetryableTransactionCancellation as d$, type TransactionItemType as d0, type UniqueEffect as d1, type Updatable as d2, type UpdateOptions as d3, type ViewSourceSlice as d4, type WhenSpec as d5, type WriteCtx as d6, type WriteDescriptor as d7, type WriteEnvelope as d8, type WriteInput as d9, executePut as dA, executeQueryMethod as dB, executeRangeFanout as dC, executeTransaction as dD, executeUpdate as dE, from as dF, getEntityWrites as dG, gsi as dH, identity as dI, isColumn as dJ, isCommandModelContract as dK, isCommandPlan as dL, isContractComposeNode as dM, isContractFromRef as dN, isContractKeyFieldRef as dO, isContractKeyRef as dP, isContractParamRef as dQ, isEntityWritesDefinition as dR, isKeySegment as dS, isLifecycleContract as dT, isMaintainTrigger as dU, isMutationFragment as dV, isMutationInputRef as dW, isParam as dX, isPlannedCommandMethod as dY, isQueryModelContract as dZ, isRetryableError as d_, type WriteKind as da, type WriteLifecyclePhase as db, type WriteMiddleware as dc, type WriteOperationType as dd, type WriteRecorder as de, type WriteResultProjection as df, attachModelClass as dg, buildDeleteInput as dh, buildMaintenanceGraph as di, buildPutInput as dj, buildSubscribeHandler as dk, buildUpdateInput as dl, collectViewDefinitions as dm, compileFragment as dn, compileMutationPlan as dp, compileSingleFragmentPlan as dq, cond as dr, contractOfMethodSpec as ds, definePlan as dt, entityWrites as du, executeBatchGet as dv, executeBatchWrite as dw, executeCommandMethod as dx, executeDelete as dy, executeKeyedBatchGet as dz, type BatchExecOptions as e, k as e0, key as e1, lifecyclePhaseForIntent as e2, maintainTrigger as e3, mintContractKeyFieldRef as e4, mintContractParamRef as e5, mutation as e6, param as e7, preview as e8, publicCommandModel as e9, publicQueryModel as ea, query as eb, resolveLifecycle as ec, wholeKeysSentinel as ed, DDBModel as f, type PrimaryKeyOf as g, type RequestContext as h, type Middleware as i, type ReadRequestKind as j, type CtxModel as k, type ReadParams as l, type ReadRequestCtx as m, type RetryPolicy as n, type ExecutionPlanSpec as o, type EntityMetadata as p, type ModelKind as q, type DynamoType as r, type ProjectionTransform as s, type MaintainEvent as t, type MembershipPredicate as u, type MaintainConsistency as v, type MaintainUpdateMode as w, type MembershipPredicateOp as x, type RelationOptions as y, type AggregateValue as z };
+/**
+ * Decorator-metadata → maintenance-graph `ViewDefinition` adapter (issue #152).
+ *
+ * ## What this replaces
+ *
+ * The old `defineView` / `defineVersioned` builders (deleted) registered
+ * `ViewDefinition`s into a side `ViewRegistry`, which the maintenance graph read.
+ * That builder carried a registration side-effect + a `generation` counter (a
+ * silent-drop guard). This adapter removes that whole path: it derives the SAME
+ * `ViewDefinition` IR purely from the declarative `MetadataRegistry` — the
+ * Contract-layer SSoT, whose own `generation` counter is the single
+ * invalidation source — so a view declared via `@model({ kind })` + `@maintainedFrom`
+ * (and a versioned relation declared via `@hasOne/@hasMany` `pattern`) is discovered
+ * with no separate registry.
+ *
+ * ## IR invariance
+ *
+ * The `ViewDefinition` / `ViewSourceSlice` shapes are UNCHANGED. The maintenance
+ * graph, the K (#130) stream/drain, and the L (#131) rebuild consume the adapter's
+ * output exactly as they consumed `ViewRegistry.getAll()`. Only the SOURCE of the
+ * definitions moved from a builder side-effect to declarative metadata.
+ *
+ * ## Order independence (issue #152 hardening)
+ *
+ * Stacked `@maintainedFrom` declarations carry no order meaning. The adapter rejects
+ * — symmetrically, so the error is identical whichever order the decorators are
+ * stacked — any two declarations on the same view that:
+ *   1. write the SAME projection target attribute (ambiguous duplicate projection);
+ *   2. maintain the SAME `collection.field`;
+ *   3. bind the SAME view-key field to a DIFFERENT source path (the view-row identity
+ *      would be inconsistent across sources).
+ * A legitimate multi-source view (different sources filling DIFFERENT fields, all
+ * binding the SAME key the SAME way) is fine.
+ */
+
+type AnyModelClass = abstract new (...args: any[]) => any;
+/** The view source slice IR the maintenance graph consumes (one per source × view). */
+interface ViewSourceSlice {
+    readonly sourceClass: AnyModelClass;
+    readonly maintainedOn: readonly MaintainTrigger[];
+    readonly keys: Readonly<Record<string, EffectPath>>;
+    readonly project: ProjectionMap;
+    readonly collection?: {
+        readonly field: string;
+        readonly maxItems?: number;
+        readonly orderBy?: EffectPath;
+        readonly orderDir?: 'ASC' | 'DESC';
+    };
+    readonly predicate?: MembershipPredicate;
+}
+/** The view definition IR — an independent view row maintained from one or more sources. */
+interface ViewDefinition {
+    readonly name: string;
+    readonly viewClass: AnyModelClass;
+    readonly pattern: 'materializedView' | 'sparseView';
+    readonly slices: readonly ViewSourceSlice[];
+    readonly updateMode?: 'mutation' | 'stream';
+    readonly consistency?: 'transactional' | 'eventual';
+}
+/**
+ * Build every {@link ViewDefinition} for a registry — from `@model({ kind })` +
+ * `@maintainedFrom` view models AND from versioned-pattern relations. This is the
+ * adapter the maintenance graph calls in place of the deleted `ViewRegistry.getAll()`.
+ *
+ * @param registry The models to scan. Defaults to `MetadataRegistry.getAll()`.
+ */
+declare function collectViewDefinitions(registry?: ReadonlyMap<Function, EntityMetadata>): ViewDefinition[];
+
+export { type BridgeBundle as $, type Param as A, type BatchResult as B, type CdcEmulatorOptions as C, type DynamoDBOperation as D, type EventLog as E, type FaultSpec as F, type QueryMethodSpec as G, type CommandModelContract as H, type CommandMethodSpec as I, type ContractSpec as J, type QuerySpec as K, type CommandSpec as L, type ModelStatic as M, type TransactionSpec as N, type ContextSpec as O, type PutInput as P, type QueryModelContract as Q, type ReplayOptions as R, type ShardId as S, type TransactWriteExecItem as T, type Unsubscribe as U, type ViewDefinition as V, type WriteExecOptions as W, type DefinitionMap as X, type OperationsDocument as Y, type AnyOperationDefinition as Z, type Manifest as _, type CdcMode as a, type DynamoType as a$, type ConditionSpec as a0, type CommandContractMethodSpec as a1, type CommandResolutionTarget as a2, type CompiledFragment as a3, type CompiledMutationPlan as a4, type ComposeSpec as a5, type CompositionPlanSpec as a6, type ContractCardinality as a7, type ContractCommandResult as a8, type ContractInputArity as a9, type ReadOperationType as aA, SPEC_VERSION as aB, type TransactionItemSpec as aC, type TransactionItemType as aD, type WhenSpec as aE, type WriteOperationType as aF, assertNoCrossFragmentMaintainCollision as aG, compileFragment as aH, compileMutationPlan as aI, compileSingleFragmentPlan as aJ, resetMaintenanceGraphCache as aK, resolveLifecycle as aL, resolveMaintainers as aM, type SelectableOf as aN, type PrimaryKeyOf as aO, type RequestContext as aP, type Middleware as aQ, type ReadRequestKind as aR, type CtxModel as aS, type ReadParams as aT, type ReadRequestCtx as aU, type Item as aV, type RetryPolicy as aW, type KeyDefinition as aX, type GsiDefinition as aY, type ModelKind as aZ, type FieldOptions as a_, type ContractKeySpec as aa, type ContractKind as ab, type ContractResolution as ac, type DerivedConditionCheck as ad, type DerivedEdgeWrite as ae, type DerivedIdempotencyGuard as af, type DerivedMaintainOutbox as ag, type DerivedMaintainWrite as ah, type DerivedOutboxEvent as ai, type DerivedUniqueGuard as aj, type DerivedUpdate as ak, type EntityRefResolver as al, type ExecutionPlanSpec as am, type FilterSpec as an, MAX_TRANSACT_COMPOSE_ITEMS as ao, type ManifestEntity as ap, type ManifestField as aq, type ManifestFieldType as ar, type ManifestGsi as as, type ManifestKey as at, type ManifestRelation as au, type ManifestTable as av, type OperationSpec as aw, type ParamSpec as ax, type QueryContractMethodSpec as ay, type RangeConditionSpec as az, type ChangeBatch as b, type DeleteOptions as b$, type ProjectionTransform as b0, type MaintainEvent as b1, type MembershipPredicate as b2, type MaintainConsistency as b3, type MaintainUpdateMode as b4, type MembershipPredicateOp as b5, type RelationOptions as b6, type AggregateOptions as b7, type AggregateValue as b8, type SelectBuilderSpec as b9, type CollectionOptions as bA, type Column as bB, type ColumnMap as bC, type CommandInputShape as bD, type CommandMethod as bE, type CommandPlan as bF, type CommandResultKind as bG, type CommandSelectShape as bH, type CondSlot as bI, type ConditionCheckInput as bJ, type Connection as bK, type ContractCallSignature as bL, type ContractCommandParams as bM, type ContractComposeNode as bN, type ContractFromRef as bO, type ContractItem as bP, type ContractKeyFieldRef as bQ, type ContractKeyInput as bR, type ContractKeyRef as bS, type ContractMethodOp as bT, type ContractParamRef as bU, type ContractQueryParams as bV, type CounterAggregate as bW, type CounterEffect as bX, type CtxBase as bY, DEFAULT_MAX_ATTEMPTS as bZ, DEFAULT_RETRY_POLICY as b_, type RawCondition as ba, type RetryOverride as bb, type ExecutionPlan as bc, type FieldMetadata as bd, type ResolvedKey as be, type RelationMetadata as bf, type MaintainEffect as bg, type OperationDefinition as bh, type WriteDefinitionOptions as bi, type PartialQueryKeyOf as bj, type StrictSelectSpec as bk, type ReadDefinitionOptions as bl, type EntityInput as bm, type UniqueQueryKeyOf as bn, type AggregateMetadata as bo, type BatchDeleteRequest as bp, type BatchGetOptions as bq, type BatchGetRequest as br, BatchGetResult as bs, type BatchPutRequest as bt, type BatchWriteRequest as bu, CONTRACT_RANGE_FANOUT_CONCURRENCY as bv, type CdcModelRegistry as bw, type CdcSubscribeHandlers as bx, type Change as by, type CollectionEffect as bz, type ChangeEvent as c, type RecordedCompose as c$, type DeriveEffect as c0, type DescriptorBinding as c1, ENTITY_WRITES_MARKER as c2, type EdgeEffect as c3, type EffectPath as c4, type EmbeddedMetadata as c5, type EmitEffect as c6, type EntityWritesDefinition as c7, type EntityWritesShape as c8, type ExecutableCommandContract as c9, type MutationBody as cA, type MutationDescriptorMap as cB, type MutationFragment as cC, type MutationInputProxy as cD, type MutationInputRef as cE, type MutationIntent as cF, type NumberParam as cG, type OperationKind as cH, type ParallelOpResult as cI, type ParamKind as cJ, type ParamStructure as cK, type PersistCtx as cL, type PersistOrigin as cM, type PlannedCommandMethod as cN, type ProjectionMap as cO, type ProjectionTransformOp as cP, type PutOptions as cQ, type QueryEnvelopeResult as cR, type QueryKeyOf as cS, type QueryMethod as cT, type QueryResult as cU, type ReadEnvelope as cV, type ReadOpCtx as cW, type ReadOpKind as cX, type ReadRouteDescriptor as cY, type ReadRouteOptions as cZ, type ReadRouteResult as c_, type ExecutableQueryContract as ca, type FilterInput as cb, type FragmentInput as cc, type GsiDefinitionMarker as cd, type GsiOptions as ce, type IdempotencyEffect as cf, type InProcessWriteDescriptor as cg, type InputArity as ch, type KeyDefinitionMarker as ci, type KeySegment as cj, type KeySlot as ck, type KeyStructure as cl, type KeyedResult as cm, LIFECYCLE_CONTRACT_MARKER as cn, type LifecycleContract as co, type LifecycleEffects as cp, type LiteralParam as cq, type MaintainItem as cr, type MaintainTrigger as cs, type MaintenanceGraph as ct, type MembershipEffect as cu, type ModelRef as cv, type MutateMode as cw, type MutateOptions as cx, type MutateParallelResult as cy, type MutateTransactionResult as cz, type ChangeEventName as d, isContractFromRef as d$, type RelationBuilder as d0, type RelationConsistency as d1, type RelationLimitOptions as d2, type RelationPattern as d3, type RelationProjection as d4, type RelationReadOptions as d5, type RelationSelect as d6, type RelationSpec as d7, type RelationUpdateMode as d8, type RelationWriteOptions as d9, buildDeleteInput as dA, buildMaintenanceGraph as dB, buildPutInput as dC, buildUpdateInput as dD, collectViewDefinitions as dE, cond as dF, contractOfMethodSpec as dG, definePlan as dH, entityWrites as dI, executeBatchGet as dJ, executeBatchWrite as dK, executeCommandMethod as dL, executeDelete as dM, executeKeyedBatchGet as dN, executePut as dO, executeQueryMethod as dP, executeRangeFanout as dQ, executeTransaction as dR, executeUpdate as dS, from as dT, getEntityWrites as dU, gsi as dV, identity as dW, isColumn as dX, isCommandModelContract as dY, isCommandPlan as dZ, isContractComposeNode as d_, type RequiresEffect as da, type Resolution as db, type RetryInfo as dc, type RetryOperationKind as dd, type SegmentSpec as de, type SegmentedKey as df, type SelectBuilder as dg, type SelectOf as dh, type SnapshotEffect as di, type StringParam as dj, TransactionContext as dk, type UniqueEffect as dl, type Updatable as dm, type UpdateOptions as dn, type ViewSourceSlice as dp, type WriteCtx as dq, type WriteDescriptor as dr, type WriteEnvelope as ds, type WriteInput as dt, type WriteKind as du, type WriteLifecyclePhase as dv, type WriteMiddleware as dw, type WriteRecorder as dx, type WriteResultProjection as dy, attachModelClass as dz, type ChangeHandler as e, isContractKeyFieldRef as e0, isContractKeyRef as e1, isContractParamRef as e2, isEntityWritesDefinition as e3, isKeySegment as e4, isLifecycleContract as e5, isMaintainTrigger as e6, isMutationFragment as e7, isMutationInputRef as e8, isParam as e9, isPlannedCommandMethod as ea, isQueryModelContract as eb, isRetryableError as ec, isRetryableTransactionCancellation as ed, k as ee, key as ef, lifecyclePhaseForIntent as eg, maintainTrigger as eh, mintContractKeyFieldRef as ei, mintContractParamRef as ej, mutation as ek, param as el, preview as em, publicCommandModel as en, publicQueryModel as eo, query as ep, wholeKeysSentinel as eq, type ClockMode as f, type ConcurrentRecomputeRef as g, type StartingPosition as h, type StreamViewType as i, type SubscribeHandler as j, type SubscribeHandlers as k, buildSubscribeHandler as l, type EntityMetadata as m, type Executor as n, type ReadExecOptions as o, type ExecutorResult as p, type BatchGetExecInput as q, type WriteResult as r, type UpdateInput as s, type DeleteInput as t, type BatchWriteExecItem as u, type BatchExecOptions as v, DDBModel as w, type ParamDescriptor as x, type EntityRef as y, type ConditionInput as z };

package/dist/registry-BD_5Rm5C.d.ts

@@ -0,0 +1,76 @@
+import { m as EntityMetadata } from './maintenance-view-adapter-D5t9taTE.js';
+
+interface LintRule {
+    id: string;
+    severity: 'error' | 'warning';
+    check(metadata: EntityMetadata, registry: typeof MetadataRegistry): LintResult[];
+}
+interface LintResult {
+    ruleId: string;
+    severity: 'error' | 'warning';
+    message: string;
+    entity: string;
+    field?: string;
+}
+
+declare class Linter {
+    private rules;
+    addRule(rule: LintRule): void;
+    run(metadata: EntityMetadata, registry: typeof MetadataRegistry): LintResult[];
+    runAll(registry: typeof MetadataRegistry): LintResult[];
+}
+
+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;
+    static getAll(): Map<Function, EntityMetadata>;
+    /**
+     * Snapshot of the entities that are **already finalized**, WITHOUT triggering
+     * finalize on any pending entity (unlike {@link getAll}). This is the safe view
+     * for a cross-entity lint rule that runs *inside* `finalize`: eagerly
+     * finalizing the rest of the registry from within a finalize pass would
+     * re-enter (and duplicate) the in-progress entity's finalize. A whole-registry
+     * rule instead reasons over the already-finalized peers plus the entity
+     * currently being checked; any conflicting pair is caught when the later of the
+     * two finalizes (both are present by then).
+     *
+     * @internal — for cross-entity linter rules.
+     */
+    static getFinalized(): Map<Function, EntityMetadata>;
+    static get linter(): Linter | null;
+    static set linter(linter: Linter | null);
+    /** Resets linter to the environment default (built-in rule set outside production). */
+    static resetLinter(): void;
+    /**
+     * @internal — for testing only. Resets to a no-op linter (no rules): matches
+     * the pre-#189 `new Linter()` behaviour where a cleared registry does not lint
+     * on re-registration. `null` is finalize-equivalent to an empty linter (the
+     * `finalize` guard skips a null linter), and nothing reads the linter getter
+     * to invoke it, so this preserves existing test semantics without importing
+     * the `Linter` class as a value (keeping it out of a production bundle).
+     */
+    static clear(): void;
+    private static finalize;
+    private static handleLintResults;
+}
+
+export { type LintRule as L, MetadataRegistry as M, type LintResult as a, Linter as b };