graphddb 0.1.0 → 0.2.0

package/dist/types-CDrWiPxp.d.ts

@@ -1,1203 +0,0 @@
-import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
-
-interface RangeCondition {
-    operator: 'begins_with';
-    key: string;
-    value: unknown;
-}
-interface DynamoDBOperationBase {
-    tableName: string;
-    projectionExpression?: string;
-    expressionAttributeNames?: Record<string, string>;
-    consistentRead?: boolean;
-    /**
-     * Server-side DynamoDB FilterExpression (independent of the
-     * KeyConditionExpression and ProjectionExpression). Names/values here are
-     * merged into the command's ExpressionAttributeNames/Values by the executor.
-     */
-    filterExpression?: string;
-    filterExpressionAttributeNames?: Record<string, string>;
-    filterExpressionAttributeValues?: Record<string, unknown>;
-}
-interface GetItemOperation extends DynamoDBOperationBase {
-    type: 'GetItem';
-    keyCondition: Record<string, unknown>;
-}
-interface QueryOperation extends DynamoDBOperationBase {
-    type: 'Query';
-    indexName?: string;
-    keyCondition: Record<string, unknown>;
-    rangeCondition?: RangeCondition;
-    scanIndexForward?: boolean;
-    limit?: number;
-    exclusiveStartKey?: Record<string, unknown>;
-}
-interface BatchGetItemOperation extends DynamoDBOperationBase {
-    type: 'BatchGetItem';
-    keys: Record<string, unknown>[];
-}
-type DynamoDBOperation = GetItemOperation | QueryOperation | BatchGetItemOperation;
-interface ExecutionPlan {
-    operations: DynamoDBOperation[];
-}
-type ResolvedKey = {
-    type: 'pk';
-    partial: boolean;
-    inputFieldNames: string[];
-} | {
-    type: 'gsi';
-    indexName: string;
-    unique: boolean;
-    partial: boolean;
-    inputFieldNames: string[];
-};
-
-/**
- * Internal brand identifying a {@link RawCondition} produced by {@link cond}.
- */
-declare const RAW_COND: unique symbol;
-/**
- * A compiled raw filter fragment produced by the {@link cond} escape hatch.
- * Column references are pre-resolved to `#`-aliased placeholders and embedded
- * values to `:`-aliased parameters; the executor merges these alongside the
- * declarative filter's names/values.
- *
- * @typeParam M - The owning model brand. A `cond` is only assignable to a
- *   `FilterInput<M>` of the same model, so embedding a different model's column
- *   is a compile error.
- */
-interface RawCondition<M = unknown> {
-    readonly [RAW_COND]: true;
-    /** @internal phantom — owning-model brand. */
-    readonly __model?: M;
-    /** Expression fragment with `{name}` / `{value}` markers already inlined. */
-    readonly template: TemplateStringsArray;
-    /** The interpolated parts, each either a Column ref or an embedded value. */
-    readonly parts: unknown[];
-}
-/**
- * The interpolation slot type accepted by {@link cond}. A column reference
- * (`Model.col.<field>`) — required for naming a column — or an embedded value
- * that is type-checked against that column. Bare column-name strings are NOT
- * accepted; you must use a {@link Column} reference, which keeps the fragment
- * refactor-safe.
- *
- * @typeParam M - The owning model brand. Constrains all columns to one model,
- *   so passing another model's column is a compile error.
- */
-type CondSlot<M> = Column<any, M> | string | number | boolean | Date;
-/**
- * Raw DynamoDB condition escape hatch.
- *
- * Use only for conditions the declarative operator objects cannot express.
- * Column names MUST be embedded via `Model.col.<field>` references (never bare
- * strings); values are embedded directly and parameterized.
- *
- * @example
- * ```ts
- * filter: cond`${User.col.age} > ${18} and attribute_exists(${User.col.email})`
- * ```
- */
-declare function cond<M = unknown>(template: TemplateStringsArray, ...parts: CondSlot<M>[]): RawCondition<M>;
-
-/**
- * Type-safe attribute condition API (DynamoDB `FilterExpression`).
- *
- * Modeled on AWS AppSync's `ModelFilterInput`: field keys map to either an
- * equality shorthand (a bare value) or an operator object. Operators are
- * constrained per field type so that e.g. `beginsWith` on a numeric field is a
- * compile error. Logical groups are expressed with the reserved `and` / `or`
- * keys (arrays) and `not` (a single nested filter).
- *
- * The condition is typed against the *full* Entity `T` (its scalar fields),
- * **not** the `select` projection — so server-side filters can reference
- * attributes that are not projected, and nested-relation filters stay fully
- * type-checked without callbacks (this is what structurally closes the #29
- * type hole).
- */
-type IsString<V> = [V] extends [string] ? true : false;
-type IsNumber<V> = [V] extends [number | bigint] ? true : false;
-/**
- * Operators common to all scalar field types.
- *
- * @typeParam V - The declared field value type.
- */
-interface CommonOperators<V> {
-    /** `#f = :v` */
-    eq?: V;
-    /** `#f <> :v` */
-    ne?: V;
-    /** `#f IN (:v0, :v1, …)` */
-    in?: readonly V[];
-    /** `attribute_exists(#f)` (true) / `attribute_not_exists(#f)` (false) */
-    attributeExists?: boolean;
-    /** `attribute_type(#f, :v)` — DynamoDB attribute type code, e.g. `'S'`, `'N'`. */
-    attributeType?: string;
-}
-/** Comparison operators valid on orderable (string / number / Date) fields. */
-interface ComparableOperators<V> {
-    /** `#f > :v` */
-    gt?: V;
-    /** `#f >= :v` */
-    ge?: V;
-    /** `#f < :v` */
-    lt?: V;
-    /** `#f <= :v` */
-    le?: V;
-    /** `#f BETWEEN :lo AND :hi` */
-    between?: readonly [V, V];
-}
-/** Operators valid only on string fields. */
-interface StringOnlyOperators {
-    /** `begins_with(#f, :v)` */
-    beginsWith?: string;
-    /** `contains(#f, :v)` */
-    contains?: string;
-    /** `NOT contains(#f, :v)` */
-    notContains?: string;
-    /** `size(#f) = :v` (string length) */
-    size?: number;
-}
-/**
- * The operator object accepted for a field of value type `V`.
- *
- * - string  → common + comparable + string-only (`beginsWith`, `contains`, …)
- * - number  → common + comparable (no `beginsWith` / `contains`)
- * - Date    → common + comparable (compared against `Date`)
- * - boolean → common only
- * - other   → common only
- */
-type FieldCondition<V> = IsString<V> extends true ? CommonOperators<V> & ComparableOperators<V> & StringOnlyOperators : IsNumber<V> extends true ? CommonOperators<V> & ComparableOperators<V> : [NonNullable<V>] extends [Date] ? CommonOperators<V> & ComparableOperators<V> : CommonOperators<V>;
-/** A field key may be given as an equality shorthand or an operator object. */
-type FieldFilter<V> = V | FieldCondition<V>;
-/**
- * Same scalar classification used across the public API: a field is filterable
- * when its value type is a leaf scalar (string/number/boolean/Date/bigint/…),
- * not a relation (`DDBModel` / `DDBModel[]`) or embedded object.
- */
-type FilterableScalar = string | number | boolean | bigint | Date | null | undefined;
-/**
- * The set of filterable scalar field keys of `T` (relations and embedded
- * objects excluded). Mirrors the projection rules in `selectable.ts`.
- */
-type ScalarKeys<T> = {
-    [K in keyof T]: T[K] extends Function ? never : T[K] extends Array<infer E> ? [E] extends [DDBModel] ? never : K : NonNullable<T[K]> extends DDBModel ? never : NonNullable<T[K]> extends FilterableScalar ? K : never;
-}[keyof T];
-/**
- * AppSync `ModelFilterInput`-compatible filter for the full Entity `T`.
- *
- * Field keys (scalar attributes of `T`) accept an equality shorthand or an
- * operator object; the reserved `and` / `or` keys take arrays of nested
- * filters and `not` takes a single nested filter.
- */
-type FilterInput<T> = ({
-    [K in ScalarKeys<T>]?: FieldFilter<T[K]>;
-} & {
-    and?: readonly (FilterInput<T> | RawCondition<T>)[];
-    or?: readonly (FilterInput<T> | RawCondition<T>)[];
-    not?: FilterInput<T> | RawCondition<T>;
-}) | RawCondition<T>;
-
-/**
- * Internal brand symbol identifying a compiled select builder at runtime.
- * Consumers should not depend on this; it is used by the execution layer to
- * distinguish a builder instance from a plain select object.
- */
-declare const SELECT_BUILDER: unique symbol;
-/**
- * The normalized spec a select builder resolves to. This is the shape the
- * planner / traversal layer consumes. `filter` is the declarative server-side
- * DynamoDB FilterExpression input.
- *
- * @internal
- */
-interface SelectBuilderSpec {
-    readonly [SELECT_BUILDER]: true;
-    select: Record<string, unknown>;
-    filter?: Record<string, unknown>;
-    limit?: number;
-    after?: string;
-    order?: 'ASC' | 'DESC';
-}
-/**
- * Top-level select builder produced by `Model.project(...)`.
- *
- * Two-stage, model-bound inference: the entity type `T` is fixed by the model,
- * and the projection `S` is inferred from the `project(...)` argument.
- *
- * `.filter(...)` is the declarative server-side DynamoDB FilterExpression,
- * typed against the full Entity `T` (so it may reference unprojected attributes
- * and type-checks operators / value types).
- *
- * @typeParam T - The (model-bound) Entity type.
- * @typeParam S - The (fixed) select projection.
- */
-interface SelectBuilder<T, S> {
-    /** Declarative server-side DynamoDB FilterExpression, typed against `T`. */
-    filter(filter: FilterInput<T>): SelectBuilder<T, S>;
-}
-/**
- * Relation select builder produced by `Model.relation(...)`. Same model-bound
- * two-stage inference as {@link SelectBuilder}, plus per-relation pagination
- * controls.
- *
- * @typeParam T - The (model-bound) relation target Entity type.
- * @typeParam S - The (fixed) select projection for this relation.
- */
-interface RelationBuilder<T, S> {
-    filter(filter: FilterInput<T>): RelationBuilder<T, S>;
-    limit(limit: number): RelationBuilder<T, S>;
-    after(cursor: string): RelationBuilder<T, S>;
-    order(order: 'ASC' | 'DESC'): RelationBuilder<T, S>;
-}
-/**
- * Extracts the projection `S` carried by a top-level or relation builder.
- * Used by `QueryResult` so a builder in a select position resolves to the same
- * result type as the bare projection it wraps.
- */
-type SelectOf<B> = B extends SelectBuilder<infer _T, infer S> ? S : B extends RelationBuilder<infer _RT, infer RS> ? RS : never;
-
-type Scalar = string | number | boolean | bigint | symbol | null | undefined | Date | Uint8Array | Set<any>;
-/**
- * Derives the select specification type from an Entity type.
- *
- * - Scalar fields → `true`
- * - Embedded objects (non-DDBModel) → nested `SelectableOf<E>`
- * - hasMany relations (`DDBModel[]`) → `RelationSelect<E>`
- * - belongsTo/hasOne relations (`DDBModel | null`) → `RelationSelect<E>`
- * - Function properties → excluded
- */
-type SelectableOf<T> = {
-    [K in keyof T as T[K] extends Function ? never : K]?: T[K] extends Array<infer E> ? [E] extends [DDBModel] ? RelationSpec<E> : true : NonNullable<T[K]> extends DDBModel ? null extends T[K] ? RelationSpec<NonNullable<T[K]>> : SelectableOf<T[K]> : T[K] extends Scalar ? true : SelectableOf<T[K]>;
-};
-/**
- * What a relation field accepts in a `select`: either the plain
- * {@link RelationSelect} object, or a {@link RelationBuilder} produced by the
- * target model's `Model.relation(...)`. The model-bound builder pins the
- * relation's target type, so passing another model's builder here is a compile
- * error (closes #33).
- */
-type RelationSpec<T> = RelationSelect<T> | RelationBuilder<T, any>;
-/**
- * Plain-object selection spec for a Relation field. Wraps `SelectableOf<T>`
- * with pagination controls and an optional declarative server-side `filter`
- * (typed against the full relation target `T`, so it may reference attributes
- * not in the projection).
- *
- * For arbitrary post-load TypeScript filtering, narrow as far as possible with
- * the declarative server-side `filter`, then apply any remaining JS-only
- * condition on the (already fully typed) result with `result.items.filter(...)`.
- *
- * @typeParam T - The target relation Entity type
- * @typeParam S - The select specification for this relation (inferred per call)
- */
-type RelationSelect<T, S extends SelectableOf<T> = SelectableOf<T>> = {
-    select: S;
-    limit?: number;
-    after?: string;
-    order?: 'ASC' | 'DESC';
-    filter?: FilterInput<T>;
-};
-/**
- * Strict ("exact") version of a select projection that rejects excess
- * properties.
- *
- * # Why this exists
- *
- * `query` / `list` infer the projection as a free generic parameter
- * (`<Sel extends SelectSpec<T>>`, `select: Sel`). When an object literal is
- * matched against a *bare type parameter* TypeScript infers `Sel` to the
- * literal's exact shape and then only checks the constraint
- * `Sel extends SelectSpec<T>` **structurally** — there is no object-literal
- * *freshness* (excess-property) check against a concrete target, because the
- * target (`Sel`) is whatever the literal is. `SelectableOf<T>` has all-optional
- * properties, so an extra key like `BOGUS: true` satisfies the constraint and
- * compiles. The `SelectableOf<T> | SelectBuilder<…>` union compounds this
- * (freshness checks are also suppressed against unions).
- *
- * `StrictSelect` closes the hole without `any`: it maps every key of the
- * inferred `Sel` that is **not** a known key of `SelectableOf<T>` to `never`.
- * Used as an *additional* constraint at the call site
- * (`select: Sel & StrictSelect<T, Sel>`), a stray key forces that property's
- * type to `never`, which the supplied `true` (or nested object) is not
- * assignable to — so the call is a compile error. Known keys keep their
- * inferred value type, so the result-type inference (`QueryResult`) and the
- * builder branch are unaffected.
- *
- * Recurses into the plain-object nested forms so the same rejection applies to
- * nested **relation** selects (`{ select: { … } }`) and **embedded** object
- * selects. Builder values (`RelationBuilder` / `SelectBuilder`) are left as-is —
- * their projection was already constrained to `SelectableOf<T>` when the
- * `Model.relation(...)` / `Model.project(...)` factory produced them.
- *
- * @typeParam T   - The Entity type the projection is taken against.
- * @typeParam Sel - The inferred select object (per call).
- */
-type StrictSelect<T, Sel> = {
-    [K in keyof Sel]: K extends keyof SelectableOf<T> ? Sel[K] extends {
-        select: infer Nested;
-    } ? K extends keyof T ? Sel[K] & {
-        select: StrictSelect<RelationTargetOf<T[K]>, Nested>;
-    } : Sel[K] : Sel[K] extends object ? Sel[K] extends RelationBuilder<infer _RT, infer _RS> ? Sel[K] : K extends keyof T ? Sel[K] & StrictSelect<NonNullable<T[K]>, Sel[K]> : Sel[K] : Sel[K] : never;
-};
-/**
- * Extracts the relation **target entity type** from an entity field type:
- * `E[]` → `E`, `E | null` → `E`. Mirrors the helper in `select-builder.ts`;
- * used by {@link StrictSelect} to recurse a nested relation select against the
- * related model's fields.
- */
-type RelationTargetOf<F> = F extends Array<infer E> ? E : NonNullable<F> extends DDBModel ? NonNullable<F> : NonNullable<F>;
-/**
- * Call-site excess-property constraint for a top-level `select` (which may be a
- * plain projection **or** a `Model.project(...)` builder).
- *
- * - If `Sel` is a {@link SelectBuilder}, it passes through untouched — the
- *   builder's projection was already constrained to `SelectableOf<T>` by the
- *   `Model.project(...)` factory, and applying {@link StrictSelect} would
- *   wrongly poison the builder's own `filter` member.
- * - Otherwise `Sel` is a plain object and {@link StrictSelect} rejects any key
- *   not declared on `T` (top-level and nested).
- *
- * Applied as `select: Sel & StrictSelectSpec<T, Sel>`, so known keys keep their
- * inferred type (result inference unaffected) and stray keys become `never`.
- *
- * @typeParam T   - The Entity type the projection is taken against.
- * @typeParam Sel - The inferred select spec (per call).
- */
-type StrictSelectSpec<T, Sel> = Sel extends SelectBuilder<any, any> ? Sel : StrictSelect<T, Sel>;
-/**
- * Derives the persistable input type for `put()` from an Entity type.
- *
- * - Function properties → excluded
- * - Relation fields (`DDBModel[]`, `DDBModel | null`) → excluded
- *   (relations are not written by `put`)
- * - Scalar fields → kept with their declared type
- * - Embedded objects (non-`DDBModel`) → recursively `EntityInput`
- */
-type EntityInput<T> = {
-    [K in keyof T as T[K] extends Function ? never : T[K] extends Array<infer E> ? [E] extends [DDBModel] ? never : K : NonNullable<T[K]> extends DDBModel ? null extends T[K] ? never : K : K]: T[K] extends Scalar ? T[K] : NonNullable<T[K]> extends DDBModel ? EntityInput<NonNullable<T[K]>> : T[K] extends object ? EntityInput<T[K]> : T[K];
-};
-
-/**
- * Derives the return type from an Entity type `T` and a select specification `S`.
- *
- * - `S[K] === true` → `T[K]` (scalar value)
- * - `S[K]` has `select` property and `T[K]` is an array (hasMany) →
- *   `{ items: QueryResult<E, Sel>[]; cursor: string | null }`
- * - `S[K]` has `select` property and `T[K]` is nullable (belongsTo/hasOne) →
- *   `QueryResult<E, Sel> | null`
- * - `S[K]` is a plain object → nested `QueryResult` (embedded)
- * - fallback → `T[K]` (for dynamic/widened select types)
- *
- * Distributes over union types in `S` so that dynamically constructed
- * selects produce a union of result types.
- */
-
-type QueryResult<T, S> = S extends unknown ? {
-    [K in keyof S & keyof T]: S[K] extends true ? T[K] : S[K] extends RelationBuilder<infer _RT, infer Sel> ? T[K] extends Array<infer E> ? {
-        items: QueryResult<E, Sel>[];
-        cursor: string | null;
-    } : QueryResult<NonNullable<T[K]>, Sel> | null : S[K] extends {
-        select: infer Sel;
-    } ? T[K] extends Array<infer E> ? {
-        items: QueryResult<E, Sel>[];
-        cursor: string | null;
-    } : QueryResult<NonNullable<T[K]>, Sel> | null : S[K] extends Record<string, unknown> ? QueryResult<T[K], S[K]> : T[K];
-} : never;
-
-/**
- * Compile-time brand for read results that carry a hidden, resolved base-table
- * key (issue #54). A `query(..., { updatable: true })` / `list(..., { updatable:
- * true })` result is typed `QueryResult<...> & Updatable` so it can be passed
- * straight back to `update()`.
- *
- * The brand is phantom (no runtime field). Spreading / cloning / JSON
- * round-tripping a branded value produces a plain object that no longer
- * structurally matches `Updatable`, so the compiler rejects passing a
- * stripped copy where an updatable entity is required. (Runtime existence of
- * the hidden key is enforced separately by `update()`, which throws when it is
- * absent — see `resolveUpdateKey`.)
- *
- * @example
- * ```ts
- * const user = await User.query({ userId: 'u' }, { name: true }, { updatable: true });
- * if (user) await User.update(user, { name: 'New' }); // ok — branded
- * // await User.update({ ...user }, { name: 'New' }); // compile error — spread drops the brand
- * ```
- */
-declare const updatableBrand: unique symbol;
-interface Updatable {
-    readonly [updatableBrand]: true;
-}
-
-declare const GSI_MARKER: unique symbol;
-interface GsiDefinitionMarker<T extends Record<string, unknown> = Record<string, unknown>, U extends boolean = boolean> {
-    readonly [GSI_MARKER]: true;
-    readonly indexName: string;
-    readonly segmented: SegmentedKey;
-    readonly inputFieldNames: string[];
-    readonly unique: U;
-    /** @internal Phantom field for type-level input type extraction. */
-    readonly _phantom?: T;
-}
-interface GsiOptions {
-    unique?: boolean;
-}
-type GsiBuilder<T extends Record<string, unknown>> = (c: {
-    readonly [K in keyof T]-?: Column<T[K], T>;
-}) => KeyStructure;
-declare function gsi<T extends Record<string, unknown>>(indexName: string, builder: GsiBuilder<T>, options: GsiOptions & {
-    unique: true;
-}): GsiDefinitionMarker<T, true>;
-declare function gsi<T extends Record<string, unknown>>(indexName: string, builder: GsiBuilder<T>, options?: GsiOptions): GsiDefinitionMarker<T, false>;
-
-/**
- * Extracts the Primary Key input type from a model class.
- * Scans static properties for `KeyDefinitionMarker<T>` and returns `T`.
- *
- * @typeParam C - The model class constructor (`typeof UserModel`)
- */
-type PrimaryKeyOf<C> = {
-    [K in keyof C]: C[K] extends KeyDefinitionMarker<infer I> ? I : never;
-}[keyof C];
-/**
- * Union of all query key input types (PK + all GSIs).
- * Used as the constraint for `list()`.
- *
- * @typeParam C - The model class constructor (`typeof UserModel`)
- */
-type QueryKeyOf<C> = {
-    [K in keyof C]: C[K] extends KeyDefinitionMarker<infer I> ? I : C[K] extends GsiDefinitionMarker<infer I, any> ? I : never;
-}[keyof C];
-/**
- * Union of unique query key input types (PK + unique GSIs only).
- * Used as the constraint for `query()` — only keys guaranteed to
- * return a single item are allowed.
- *
- * @typeParam C - The model class constructor (`typeof UserModel`)
- */
-type UniqueQueryKeyOf<C> = {
-    [K in keyof C]: C[K] extends KeyDefinitionMarker<infer I> ? I : C[K] extends GsiDefinitionMarker<infer I, true> ? I : never;
-}[keyof C];
-/**
- * "At least one" relaxation of a single key input type `T`: every field is
- * known and correctly typed, but only a non-empty subset need be supplied (the
- * remaining fields become optional).
- *
- * For a composite key `{ groupId: string; userId: string }` this yields
- * `{ groupId: string; userId?: string } | { groupId?: string; userId: string }`
- * — i.e. you may supply just the partition-key field(s) without the full
- * sort-key tail. Unknown fields are still rejected (object-literal excess
- * property checking), so it stays strictly typed.
- */
-type AtLeastOneKey<T> = {
-    [K in keyof T]-?: {
-        [P in K]-?: T[P];
-    } & {
-        [P in Exclude<keyof T, K>]?: T[P];
-    } extends infer O ? {
-        [P in keyof O]: O[P];
-    } : never;
-}[keyof T];
-/**
- * Key type accepted by `list()` / `explain()`. These issue a DynamoDB *Query*
- * against a partition (PK or GSI), so a **partial** key — the partition-key
- * subset of a PK/GSI input — is sufficient; the sort-key portion is optional
- * (it narrows the range, e.g. `begins_with`). This mirrors the runtime key
- * resolver, which accepts any field subset that produces a valid partition key
- * (`src/planner/key-resolver.ts`) and throws otherwise.
- *
- * Distinct from {@link QueryKeyOf} (full key, used as the constraint label by
- * the type tests) and {@link UniqueQueryKeyOf} (full unique key for `query()`,
- * which must resolve to a single item). `query()` deliberately stays strict —
- * only this `list`/`explain` boundary is relaxed.
- *
- * @typeParam C - The model class constructor (`typeof UserModel`)
- */
-type PartialQueryKeyOf<C> = QueryKeyOf<C> extends infer U ? U extends Record<string, unknown> ? AtLeastOneKey<U> : never : never;
-
-/**
- * A top-level `select` may be either a plain projection (`SelectableOf<T>`) or
- * a {@link SelectBuilder} produced by `Model.project(...)`. The builder is
- * model-bound to `T`, so its `.filter(...)` is typed against the full entity.
- */
-type SelectSpec<T> = SelectableOf<T> | SelectBuilder<T, any>;
-/**
- * Resolves the projection `S` from a top-level select spec (plain object or
- * builder), so the result type is computed identically for both forms.
- */
-type ProjectionOf<T, Sel> = Sel extends SelectableOf<T> ? Sel : SelectOf<Sel>;
-/**
- * Default model-class constraint used when a `ModelStatic` is referenced
- * without its concrete constructor type (e.g. `ModelStatic<UserModel>`).
- *
- * In that case key/option types fall back to permissive shapes so existing
- * usages keep compiling, while the precise inference is available when the
- * constructor type is supplied (as it is from `DDBModel.asModel()`).
- */
-type AnyModelClass = abstract new (...args: any[]) => DDBModel;
-/**
- * The accepted PK / GSI key type for `list()` / `explain()`.
- *
- * `list`/`explain` issue a DynamoDB *Query* against a partition, so a **partial**
- * key (partition-key subset of a PK/GSI input) is accepted — the sort-key tail
- * is optional. This matches the runtime key resolver. `query()` stays strict via
- * {@link QueryKey}. Derived from the model class when available, otherwise
- * permissive.
- */
-type ListKey<C> = [C] extends [AnyModelClass] ? PartialQueryKeyOf<C> : Record<string, unknown>;
-/**
- * The accepted key type for `query()` — only keys guaranteed to return a
- * single item (PK + unique GSIs). Derived from the model class when available.
- */
-type QueryKey<C> = [C] extends [AnyModelClass] ? UniqueQueryKeyOf<C> : Record<string, unknown>;
-/**
- * The accepted key type for `delete()` (PK only). Derived from the model
- * class when available.
- */
-type DeleteKey<C> = [C] extends [AnyModelClass] ? PrimaryKeyOf<C> : Record<string, unknown>;
-/**
- * The accepted *explicit* key type for `update()` — the base-table primary key
- * only. DynamoDB `UpdateItem` can target an item solely by its base-table PK
- * (GSI-based updates are impossible), so this is `PrimaryKeyOf<C>`, not
- * `UniqueQueryKeyOf<C>`. Derived from the model class when available.
- */
-type UpdateExplicitKey<C> = [C] extends [AnyModelClass] ? PrimaryKeyOf<C> : Record<string, unknown>;
-/**
- * Options accepted by `list()`.
- *
- * - `select` is either a plain projection or a `project(...)` builder.
- * - `filter` is the declarative server-side DynamoDB FilterExpression, typed
- *   against the full Entity `T` (may reference unprojected attributes). For
- *   arbitrary JS-only post-load filtering, narrow with `filter` then apply
- *   `result.items.filter(...)` (already fully typed).
- *
- * @typeParam T   - The Entity type.
- * @typeParam Sel - The select spec (plain object or builder), inferred per call.
- */
-type ListCallOptions<T, Sel extends SelectSpec<T>> = {
-    select: Sel & StrictSelectSpec<T, Sel>;
-    limit?: number;
-    after?: string;
-    order?: 'ASC' | 'DESC';
-    filter?: FilterInput<T>;
-    /**
-     * When `true`, each returned item is updatable: it carries its resolved
-     * base-table key as a hidden, non-enumerable property and is branded
-     * `& Updatable`, so it can be passed straight back to `update()`.
-     */
-    updatable?: boolean;
-};
-/**
- * Public, type-inferring API surface produced by {@link DDBModel.asModel}.
- *
- * @typeParam T - The Entity type of the model.
- * @typeParam C - The model class constructor type. Supplied automatically by
- *   `asModel()`; when omitted, key/option types widen to permissive shapes so
- *   that `ModelStatic<T>` keeps compiling for callers that only name the entity.
- */
-interface ModelStatic<T extends DDBModel, C = unknown> {
-    /**
-     * Type-safe column references for this model, one per scalar field. Used by
-     * the `cond` raw escape hatch (`cond\`${Model.col.age} > ${18}\``). Each
-     * column carries its declared type and is branded to this model, so passing
-     * another model's column into this model's `cond` is a compile error.
-     */
-    readonly col: ColumnMap<T>;
-    /**
-     * Begin a model-bound, top-level select builder. The entity type `T` is fixed
-     * by this model and the projection `S` is inferred from the argument.
-     * `.filter(...)` is typed `FilterInput<T>` against the full entity.
-     *
-     * @example
-     * ```ts
-     * Order.list({ userId: 'u' }, {
-     *   select: Order.project({ orderId: true, amount: true })
-     *     .filter({ status: 'confirmed', amount: { gt: 100 } }),
-     * });
-     * ```
-     */
-    project<const S extends SelectableOf<T>>(select: S): SelectBuilder<T, S>;
-    /**
-     * Begin a model-bound relation select builder for use as a relation field's
-     * value inside a parent `select`. `T` is this (relation target) model's
-     * entity type; `S` is inferred from the argument. Same model-bound inference
-     * as {@link ModelStatic.project}, plus per-relation pagination
-     * (`limit` / `after` / `order`).
-     *
-     * @example
-     * ```ts
-     * User.query({ userId: 'u' }, {
-     *   name: true,
-     *   orders: Order.relation({ orderId: true, amount: true })
-     *     .filter({ amount: { gt: 100 } }),
-     * });
-     * ```
-     */
-    relation<const S extends SelectableOf<T>>(select: S): RelationBuilder<T, S>;
-    /**
-     * Fetch a single item by a unique key and **hydrate** the plain result onto a
-     * host-side object (issue #53). The `hydrate` factory receives the fully-built
-     * plain object — `QueryResult<T, ProjectionOf<T, Sel>>`, typed against exactly
-     * the `select`ed fields — and its return type `R` becomes the read's return
-     * type (subsuming a `queryAs(Ctor, …)` style: `hydrate: (raw) => new Ctor(raw)`).
-     *
-     * Applied as the **final after-fetch step**, only to a present item: a missing
-     * item resolves to `null` and the factory is NOT invoked (hence `R | null`). A
-     * throw from the factory propagates verbatim as the read's rejection.
-     *
-     * Host-runtime ONLY: the factory is a host-language closure, never serialized
-     * into the SSoT / `operations.json`, so it does not impede the bridge (#48).
-     */
-    query<Sel extends SelectSpec<T>, R>(key: QueryKey<C>, select: Sel & StrictSelectSpec<T, Sel>, options: {
-        consistentRead?: boolean;
-        maxDepth?: number;
-        updatable?: boolean;
-        hydrate: (raw: QueryResult<T, ProjectionOf<T, Sel>>) => R;
-    }): Promise<R | null>;
-    /**
-     * Fetch a single item by a unique key, requesting an **updatable** result.
-     * The returned item (when non-null) carries its resolved base-table key as a
-     * hidden, non-enumerable property and is branded `& Updatable`, so it can be
-     * passed straight back to {@link ModelStatic.update} — even for a partial
-     * `select` or a GSI-based query. Do not spread / clone / JSON round-trip the
-     * result before updating: that drops both the hidden key and the brand.
-     */
-    query<Sel extends SelectSpec<T>>(key: QueryKey<C>, select: Sel & StrictSelectSpec<T, Sel>, options: {
-        consistentRead?: boolean;
-        maxDepth?: number;
-        updatable: true;
-    }): Promise<(QueryResult<T, ProjectionOf<T, Sel>> & Updatable) | null>;
-    /**
-     * Fetch a single item by a unique key. The return type contains only the
-     * selected fields, derived from `select`.
-     */
-    query<Sel extends SelectSpec<T>>(key: QueryKey<C>, select: Sel & StrictSelectSpec<T, Sel>, options?: {
-        consistentRead?: boolean;
-        maxDepth?: number;
-        updatable?: false;
-    }): Promise<QueryResult<T, ProjectionOf<T, Sel>> | null>;
-    /**
-     * List items for a partition. `options.select` may be a plain projection or a
-     * `project(...)` builder. `options.filter` is the declarative server-side
-     * FilterExpression typed against the full Entity. Returned items contain only
-     * the selected fields.
-     */
-    list<Sel extends SelectSpec<T>>(key: ListKey<C>, options: ListCallOptions<T, Sel> & {
-        updatable: true;
-    }): Promise<{
-        items: (QueryResult<T, ProjectionOf<T, Sel>> & Updatable)[];
-        cursor: string | null;
-    }>;
-    list<Sel extends SelectSpec<T>>(key: ListKey<C>, options: ListCallOptions<T, Sel>): Promise<{
-        items: QueryResult<T, ProjectionOf<T, Sel>>[];
-        cursor: string | null;
-    }>;
-    explain<Sel extends SelectSpec<T>>(key: ListKey<C>, options?: {
-        select?: Sel & StrictSelectSpec<T, Sel>;
-        limit?: number;
-        after?: string;
-        order?: 'ASC' | 'DESC';
-        consistentRead?: boolean;
-        filter?: FilterInput<T>;
-    }): ExecutionPlan;
-    put(item: EntityInput<T>, options?: Record<string, unknown>): Promise<void>;
-    /**
-     * Update an item identified by its **explicit base-table primary key**
-     * (`PrimaryKeyOf<C>`). This is the canonical form — it requires the key input
-     * up front, so it can never silently target the wrong item.
-     *
-     * @example `await User.update({ userId: 'alice' }, { status: 'disabled' });`
-     */
-    update(key: UpdateExplicitKey<C>, changes: Partial<T>, options?: Record<string, unknown>): Promise<void>;
-    /**
-     * Update an item using an **updatable** entity obtained from
-     * `query(..., { updatable: true })` / `list(..., { updatable: true })`. The
-     * hidden base-table key carried by that entity is used directly, so this
-     * works even for a partial `select` or a GSI-based read.
-     *
-     * Pass the entity as-is. A spread / clone / JSON round-trip drops both the
-     * brand (rejected here at compile time) and the hidden key (rejected at
-     * runtime), preventing an accidental wrong-item update.
-     */
-    update(entity: Partial<T> & Updatable, changes: Partial<T>, options?: Record<string, unknown>): Promise<void>;
-    delete(key: DeleteKey<C>, options?: Record<string, unknown>): Promise<void>;
-}
-
-interface PutOptions {
-    condition?: Record<string, unknown>;
-}
-interface UpdateOptions {
-    condition?: Record<string, unknown>;
-}
-interface DeleteOptions {
-    condition?: Record<string, unknown>;
-}
-
-interface PutInput {
-    TableName: string;
-    Item: Record<string, unknown>;
-    ConditionExpression?: string;
-    ExpressionAttributeNames?: Record<string, string>;
-    ExpressionAttributeValues?: Record<string, unknown>;
-}
-declare function buildPutInput(modelClass: Function, item: Record<string, unknown>, options?: PutOptions): PutInput;
-declare function executePut(modelClass: Function, item: Record<string, unknown>, options?: PutOptions): Promise<void>;
-
-interface UpdateInput {
-    TableName: string;
-    Key: Record<string, unknown>;
-    UpdateExpression: string;
-    ExpressionAttributeNames: Record<string, string>;
-    ExpressionAttributeValues?: Record<string, unknown>;
-    ConditionExpression?: string;
-}
-declare function buildUpdateInput(modelClass: Function, entity: Record<string, unknown>, changes: Record<string, unknown>, options?: UpdateOptions): UpdateInput;
-declare function executeUpdate(modelClass: Function, entity: Record<string, unknown>, changes: Record<string, unknown>, options?: UpdateOptions): Promise<void>;
-
-interface DeleteInput {
-    TableName: string;
-    Key: Record<string, unknown>;
-    ConditionExpression?: string;
-    ExpressionAttributeNames?: Record<string, string>;
-    ExpressionAttributeValues?: Record<string, unknown>;
-}
-declare function buildDeleteInput(modelClass: Function, keyObj: Record<string, unknown>, options?: DeleteOptions): DeleteInput;
-declare function executeDelete(modelClass: Function, keyObj: Record<string, unknown>, options?: DeleteOptions): Promise<void>;
-
-/** Result of a read operation (GetItem / Query / BatchGetItem). */
-interface ExecutorResult {
-    items: Record<string, unknown>[];
-    lastEvaluatedKey?: Record<string, unknown>;
-}
-/**
- * Result of a single structured write. `oldItem` is the pre-write image,
- * present only when the caller requested it (`returnOldImage: true`, mapped to
- * DynamoDB `ReturnValues: ALL_OLD`) and an item existed before the write. The
- * write-capture seam (issue #72) reads it to derive INSERT vs MODIFY and the
- * REMOVE OldImage.
- */
-interface WriteResult {
-    oldItem?: Record<string, unknown>;
-}
-/** Options shared by the single-item structured write methods. */
-interface WriteExecOptions {
-    /** Request the pre-write image (DynamoDB `ReturnValues: ALL_OLD`). */
-    returnOldImage?: boolean;
-}
-/**
- * One BatchGetItem sub-request: a single physical table plus its keys and an
- * optional projection. Mirrors {@link import('../planner/types.js').BatchGetItemOperation}
- * without the discriminant `type` field, so callers that already chunked keys
- * (relation traversal) and the planner-driven read path share one entry point.
- */
-interface BatchGetExecInput {
-    tableName: string;
-    keys: Record<string, unknown>[];
-    projectionExpression?: string;
-    expressionAttributeNames?: Record<string, string>;
-    consistentRead?: boolean;
-}
-/** A single item in a {@link Executor.batchWrite} request, grouped by table. */
-type BatchWriteExecItem = {
-    type: 'put';
-    item: Record<string, unknown>;
-} | {
-    type: 'delete';
-    key: Record<string, unknown>;
-};
-/**
- * A read-only `ConditionCheck` entry for {@link Executor.transactWrite} (issue
- * #81): it asserts a `ConditionExpression` holds for the keyed item without
- * mutating it. A failed assertion cancels the **whole** `TransactWriteItems`
- * atomically — the foundation for referential-integrity derivation.
- */
-interface ConditionCheckInput {
-    TableName: string;
-    Key: Record<string, unknown>;
-    ConditionExpression: string;
-    ExpressionAttributeNames?: Record<string, string>;
-    ExpressionAttributeValues?: Record<string, unknown>;
-}
-/**
- * A `{ Put | Update | Delete | ConditionCheck }` entry for
- * {@link Executor.transactWrite}. The first three mutate an item; `ConditionCheck`
- * (issue #81) is a read-only assertion on another item.
- */
-type TransactWriteExecItem = {
-    Put: PutInput;
-} | {
-    Update: UpdateInput;
-} | {
-    Delete: DeleteInput;
-} | {
-    ConditionCheck: ConditionCheckInput;
-};
-/**
- * The unified I/O seam (issue #76). All of GraphDDB's read and write I/O is
- * funneled through one injectable executor so the engine (planner / hydrator /
- * relation traversal / write paths) can run unchanged against either real
- * DynamoDB ({@link DynamoExecutor}, the default) or an in-process memory store
- * (`MemoryExecutor`, the test adapter).
- *
- * Reads take a structured {@link DynamoDBOperation}; writes take the structured
- * inputs the operation layer already builds (`PutInput` / `UpdateInput` / …),
- * never an AWS SDK command. This keeps the seam at the *structured operation
- * boundary* (proposal option B): no expression-string parsing is required to
- * implement a fake.
- */
-interface Executor {
-    /** Read path: GetItem / Query / BatchGetItem. */
-    execute(operation: DynamoDBOperation): Promise<ExecutorResult>;
-    /**
-     * BatchGetItem for a single table. The caller is responsible for chunking
-     * keys ≤100 (the relation traversal and the planner-driven path both do).
-     */
-    batchGet(input: BatchGetExecInput): Promise<ExecutorResult>;
-    /** Put one item. */
-    put(input: PutInput, options?: WriteExecOptions): Promise<WriteResult>;
-    /** Update one item (applies its structured UpdateExpression). */
-    update(input: UpdateInput, options?: WriteExecOptions): Promise<WriteResult>;
-    /** Delete one item. */
-    delete(input: DeleteInput, options?: WriteExecOptions): Promise<WriteResult>;
-    /**
-     * BatchWriteItem for a single table (non-atomic). Keys/items are chunked ≤25
-     * with UnprocessedItems retry by the implementation.
-     */
-    batchWrite(tableName: string, items: BatchWriteExecItem[]): Promise<void>;
-    /** TransactWriteItems — all-or-nothing atomic. */
-    transactWrite(items: TransactWriteExecItem[]): Promise<void>;
-}
-
-type TransactWriteItemInput = {
-    Put: PutInput;
-} | {
-    Update: UpdateInput;
-} | {
-    Delete: DeleteInput;
-} | {
-    ConditionCheck: ConditionCheckInput;
-};
-declare function attachModelClass<T extends DDBModel>(modelStatic: ModelStatic<T>, modelClass: new (...args: unknown[]) => T): ModelStatic<T>;
-/**
- * Per-item capture descriptor recorded alongside each transact item, so the
- * write-capture seam (issue #72) can emit a labelled raw record after the
- * transaction commits. `TransactWriteItems` returns no images (spec §14), so
- * these carry the keys + the new item for Put/Update and keys only for Delete.
- */
-interface TransactCaptureMeta {
-    modelName?: string;
-    op: 'put' | 'update' | 'delete';
-    table: string;
-    keys: {
-        pk: string;
-        sk: string;
-    };
-    newItem?: Record<string, unknown>;
-}
-declare class TransactionContext {
-    private readonly items;
-    private readonly captureMeta;
-    get itemCount(): number;
-    put(model: ModelStatic<DDBModel>, item: Record<string, unknown>, options?: PutOptions): void;
-    update(model: ModelStatic<DDBModel>, entity: Record<string, unknown>, changes: Record<string, unknown>, options?: UpdateOptions): void;
-    delete(model: ModelStatic<DDBModel>, key: Record<string, unknown>, options?: DeleteOptions): void;
-    /**
-     * Add a read-only `ConditionCheck` assertion on a keyed item (issue #81). The
-     * item is **not** mutated; the `options.condition` (e.g.
-     * `{ attributeExists: 'PK' }` to require the row exists) is asserted, and a
-     * failed assertion cancels the **whole** `TransactWriteItems` atomically. This
-     * is the foundation for referential-integrity derivation (proposal: `requires
-     * <Entity> exists`). A ConditionCheck emits no change-capture record (it writes
-     * nothing).
-     *
-     * @throws if `options.condition` is missing — a ConditionCheck without an
-     *   assertion is meaningless.
-     */
-    conditionCheck(model: ModelStatic<DDBModel>, key: Record<string, unknown>, options: {
-        condition: Record<string, unknown>;
-    }): void;
-    /** @internal */
-    getTransactItems(): TransactWriteItemInput[];
-    /** @internal — capture descriptors for the write-capture seam (issue #72). */
-    getCaptureMeta(): TransactCaptureMeta[];
-    private assertWithinLimit;
-}
-declare function executeTransaction(fn: (tx: TransactionContext) => void | Promise<void>): Promise<void>;
-
-interface BatchGetRequest {
-    model: ModelStatic<DDBModel>;
-    keys: Record<string, unknown>[];
-}
-interface BatchPutRequest {
-    type: 'put';
-    model: ModelStatic<DDBModel>;
-    item: Record<string, unknown>;
-    options?: PutOptions;
-}
-interface BatchDeleteRequest {
-    type: 'delete';
-    model: ModelStatic<DDBModel>;
-    key: Record<string, unknown>;
-    options?: DeleteOptions;
-}
-type BatchWriteRequest = BatchPutRequest | BatchDeleteRequest;
-declare class BatchGetResult {
-    private readonly groups;
-    constructor(groups: Map<Function, Record<string, unknown>[]>);
-    get<T extends DDBModel>(model: ModelStatic<T>): Partial<T>[];
-}
-declare function executeBatchGet(requests: BatchGetRequest[]): Promise<BatchGetResult>;
-declare function executeBatchWrite(requests: BatchWriteRequest[]): Promise<void>;
-
-declare abstract class DDBModel {
-    /** @internal Type brand — prevents primitives from structurally matching DDBModel. */
-    private readonly __brand;
-    static setClient(client: DynamoDBClient): void;
-    static setTableMapping(mapping: Record<string, string>): void;
-    static transaction(fn: (tx: TransactionContext) => void | Promise<void>): Promise<void>;
-    static batchGet(requests: BatchGetRequest[]): Promise<BatchGetResult>;
-    static batchWrite(requests: BatchWriteRequest[]): Promise<void>;
-    static asModel<C extends new (...args: never[]) => DDBModel>(this: C): ModelStatic<InstanceType<C>, C>;
-}
-
-/**
- * Internal brand identifying a {@link Column} reference at runtime, used by the
- * `cond` raw escape hatch to recognize and alias embedded column references.
- */
-declare const COLUMN_REF: unique symbol;
-/**
- * A type-safe reference to a model field (column).
- *
- * Each column carries its declared value type as a phantom parameter so the
- * `cond` escape hatch can type-check embedded values against the column. The
- * `__model` phantom brands the column to its owning model, so passing a column
- * from a different model into another model's `cond` is a type error.
- *
- * @typeParam V - The declared field value type.
- * @typeParam M - The owning model (brand only; never read at runtime).
- */
-interface Column<V = unknown, M = unknown> {
-    readonly [COLUMN_REF]: true;
-    /** The underlying attribute (property) name. */
-    readonly name: string;
-    /** @internal phantom — value type carried for `cond` value checking. */
-    readonly __value?: V;
-    /** @internal phantom — owning-model brand. */
-    readonly __model?: M;
-}
-/** Runtime guard: is this value a {@link Column} reference? */
-declare function isColumn(value: unknown): value is Column;
-/**
- * The `Model.col` map: one {@link Column} per scalar field of the entity, each
- * typed with the field's declared value type and branded to the model.
- *
- * @typeParam T - The Entity type.
- */
-type ColumnMap<T> = {
-    [K in keyof T as T[K] extends Function ? never : NonNullable<T[K]> extends DDBModel ? never : T[K] extends Array<infer E> ? [E] extends [DDBModel] ? never : K : K]: Column<T[K], T>;
-};
-
-declare const KEY_MARKER: unique symbol;
-/**
- * Brand identifying a {@link KeySegment} produced by the {@link k} tag.
- */
-declare const KEY_SEGMENT: unique symbol;
-/**
- * A single structured key segment — the output of one `` k`...` `` tagged
- * template. Its literal parts and the column references interpolated between
- * them are preserved verbatim (the column refs are NOT stringified), so the
- * planner / spec generator can derive `{field}` templates directly from the
- * structure rather than recovering them by symbolic evaluation.
- *
- * Exactly one `` k`...` `` = one segment = one truncation boundary for a
- * multi-segment sort key.
- */
-interface KeySegment {
-    readonly [KEY_SEGMENT]: true;
-    /** The literal string parts; always one longer than {@link columns}. */
-    readonly literals: readonly string[];
-    /** The interpolated column references, in order. */
-    readonly columns: readonly Column[];
-}
-/** Runtime guard: is this value a {@link KeySegment}? */
-declare function isKeySegment(value: unknown): value is KeySegment;
-/**
- * The interpolation slot accepted by {@link k}: a typed column reference
- * (`c.field`). Bare strings are NOT accepted — a key field must be named via a
- * {@link Column} reference so the structure stays type-safe and refactor-safe.
- */
-type KeySlot = Column;
-/**
- * Tagged-template builder for a single key segment.
- *
- * The literal parts and the interpolated column references are kept structurally
- * (never stringified), mirroring the {@link cond} escape hatch. A segment such
- * as `` k`USER#${c.userId}` `` becomes `{ literals: ['USER#', ''], columns: [userId] }`,
- * which the planner turns into the template `USER#{userId}`.
- *
- * @example
- * ```ts
- * key((c) => ({ pk: k`USER#${c.userId}`, sk: k`PROFILE` }));
- * key((c) => ({
- *   pk: k`REGION#${c.region}`,
- *   sk: [k`CITY#${c.city}`, k`STORE#${c.store}`],
- * }));
- * ```
- */
-declare function k(literals: TemplateStringsArray, ...columns: KeySlot[]): KeySegment;
-/** A single segment, or an ordered list of segments (multi-segment SK). */
-type SegmentSpec = KeySegment | KeySegment[];
-/** The `{ pk, sk }` structure returned by a key builder. */
-interface KeyStructure {
-    readonly pk: SegmentSpec;
-    readonly sk?: SegmentSpec;
-}
-/**
- * The canonical, structured representation of a key (PK or SK as a list of
- * segments). This — not an opaque mapping closure — is the single source of
- * truth for a model's key.
- */
-interface SegmentedKey {
-    /** Partition-key segments (all required at resolve time). */
-    readonly pkSegments: readonly KeySegment[];
-    /** Sort-key segments, evaluated in order with truncation. */
-    readonly skSegments: readonly KeySegment[];
-}
-interface KeyDefinitionMarker<T extends Record<string, unknown> = Record<string, unknown>> {
-    readonly [KEY_MARKER]: true;
-    readonly segmented: SegmentedKey;
-    readonly inputFieldNames: string[];
-    /** @internal Phantom field for type-level input type extraction. */
-    readonly _phantom?: T;
-}
-/**
- * Define a model's primary key from a **structured segment** builder.
- *
- * The builder receives a typed column accessor `c` (one `Column` per field) and
- * returns `{ pk, sk }`, where each of `pk` / `sk` is a single `` k`...` ``
- * segment or an array of them. Column references are captured structurally, so
- * the key template is recovered directly from the structure — no symbolic
- * evaluation of an opaque closure.
- *
- * @typeParam T - The key input type (drives compile-time key checking for
- *   `query` / `list`). Supplied by the caller's parameter annotation on `c`.
- */
-declare function key<T extends Record<string, unknown>>(builder: (c: {
-    readonly [K in keyof T]-?: Column<T[K], T>;
-}) => KeyStructure): KeyDefinitionMarker<T>;
-
-/**
- * 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;
-
-export { type KeyStructure as $, type CdcMode as A, type BatchGetExecInput as B, type ChangeEvent as C, type DynamoDBOperation as D, type Executor as E, type FaultSpec as F, type ChangeBatch as G, type ChangeEventName as H, type ClockMode as I, type Column as J, type ColumnMap as K, type CondSlot as L, type ModelStatic as M, type ConditionCheckInput as N, type DeleteOptions as O, type PutInput as P, type FilterInput as Q, type ResolvedKey as R, type SelectableOf as S, type TransactWriteExecItem as T, type UpdateInput as U, type GsiDefinitionMarker as V, type WriteExecOptions as W, type GsiOptions as X, type KeyDefinitionMarker as Y, type KeySegment as Z, type KeySlot as _, type ExecutorResult as a, type PutOptions as a0, type QueryKeyOf as a1, type QueryResult as a2, type RawCondition as a3, type RelationBuilder as a4, type RelationSelect as a5, type RelationSpec as a6, type SegmentSpec as a7, type SelectBuilder as a8, type SelectOf as a9, type StartingPosition as aa, type StreamViewType as ab, TransactionContext as ac, type Updatable as ad, type UpdateOptions as ae, attachModelClass as af, buildDeleteInput as ag, buildPutInput as ah, buildUpdateInput as ai, cond as aj, executeBatchGet as ak, executeBatchWrite as al, executeDelete as am, executePut as an, executeTransaction as ao, executeUpdate as ap, gsi as aq, isColumn as ar, isKeySegment as as, k as at, key as au, type WriteResult as b, type DeleteInput as c, type BatchWriteExecItem as d, DDBModel as e, type PrimaryKeyOf as f, type SegmentedKey as g, type SelectBuilderSpec as h, type ExecutionPlan as i, type CdcEmulatorOptions as j, type ChangeHandler as k, type Unsubscribe as l, type ConcurrentRecomputeRef as m, type EventLog as n, type ReplayOptions as o, type ShardId as p, type PartialQueryKeyOf as q, type StrictSelectSpec as r, type EntityInput as s, type UniqueQueryKeyOf as t, type BatchDeleteRequest as u, type BatchGetRequest as v, BatchGetResult as w, type BatchPutRequest as x, type BatchResult as y, type BatchWriteRequest as z };