graphddb 0.5.2 → 0.6.0

package/dist/index-CtJbTrfB.d.ts

@@ -0,0 +1,690 @@
+import { x as ParamDescriptor, y as EntityRef, z as ConditionInput, A as Param, M as ModelStatic, w as DDBModel, Q as QueryModelContract, G as QueryMethodSpec, H as CommandModelContract, I as CommandMethodSpec, J as ContractSpec, K as QuerySpec, L as CommandSpec, N as TransactionSpec, O as ContextSpec, X as DefinitionMap, Y as OperationsDocument, Z as AnyOperationDefinition, _ as Manifest, $ as BridgeBundle, a0 as ConditionSpec } from './maintenance-view-adapter-CFeasCKo.js';
+import { M as MetadataRegistry } from './registry-DbqmFyab.js';
+
+/**
+ * Declarative transaction definition DSL (issue #46, Python-bridge Phase 4).
+ *
+ * `defineTransaction(params, (tx, p) => { … })` captures a **single source of
+ * truth** for a `TransactWriteItems` batch: a parameter map plus a declarative
+ * instruction list (`tx.put` / `tx.update` / `tx.delete`, plus `tx.forEach` over
+ * an array param). The callback is evaluated at definition time with sentinel
+ * proxies in place of params / loop elements, so the recorded instructions carry
+ * **field-reference templates** (`{groupId}`, `{item.userId}`) rather than
+ * concrete values — exactly the shape the static planner (#42) turns into a
+ * serializable `transaction` op the TS and Python runtimes expand identically.
+ *
+ * ## Declarativity boundary (enforced — same soundness as #42 keys)
+ *
+ * The callback body may only:
+ *  - call `tx.put/update/delete(Model, …)` with **field references** (from `p`
+ *    or a `forEach` element) or **concrete literals** at scalar leaves;
+ *  - call `tx.forEach(p.<arrayParam>, (el) => { … }, { when? })` whose body is
+ *    itself only `tx.*` writes;
+ *  - attach a declarative `when` (a small comparison over field refs) and/or a
+ *    `condition` (the `{ notExists } | equality` subset, as for single writes).
+ *
+ * The same hardening that protects **key** positions (#42 `src/spec/symbolic.ts`)
+ * is applied to **value** positions (item / changes / condition values, `when`
+ * right-hand side). Value positions are in fact held to a *stricter* boundary
+ * than keys: a key may legitimately interpolate a field (`` `USER#${id}` ``), so
+ * coercion is allowed there and the differential template check is the boundary;
+ * a value leaf may **only** be a *direct* field reference or a concrete literal,
+ * so at a value position a faithful reference is **never coerced**. That single
+ * fact is the soundness boundary:
+ *
+ *  1. **Throwing sentinel Proxy.** Each param / element placeholder is a Proxy
+ *     whose `get` trap whitelists only primitive coercion
+ *     (`Symbol.toPrimitive` / `toString` / `valueOf`) and the brand / `token` /
+ *     `origin` reads the planner needs, and **throws on every other property or
+ *     method access**. So a *direct* transform on a value placeholder —
+ *     `p.role.length`, `p.role[0]`, `p.role.toUpperCase()` — fails at the access
+ *     site, exactly like a key sentinel. (Same first-line defense as #42.)
+ *  2. **Per-access coercion ledger (primary boundary).** Every minted field ref
+ *     records each time it is coerced to a primitive (`Symbol.toPrimitive` /
+ *     `toString` / `valueOf`). Because a faithful value reference is stored as
+ *     the Proxy *object* and never coerced, **any** coercion of a value ref is
+ *     positive proof the callback consumed the parameter into a transform, a
+ *     branch, an interpolation, or a comparison — and the build is rejected. This
+ *     is *access-site* accurate: it fires even when the same field is *also*
+ *     referenced faithfully elsewhere in the item (so its token still surfaces),
+ *     and it catches transforms that **converge to a constant or a shared marker
+ *     fragment** — `String(p.role).slice(0,0)` → `''`, `.slice(0,3)` → a shared
+ *     prefix, `[0]` / `.charAt(0)`, `.includes('Tx')` → a constant boolean, any
+ *     `… + 'CONST'` built atop them — which a purely output-comparing check could
+ *     not (the dropped field is masked by its faithful sibling, and the converged
+ *     value is byte-identical across passes).
+ *  3. **Differential evaluation (secondary).** The callback is evaluated **twice**,
+ *     each run delivering placeholders that coerce to a *different* per-field
+ *     marker (the two markers share no common prefix and no common substring of
+ *     length ≥ 2, and differ in length). Every recorded value leaf must be either
+ *     (a) a faithful field reference (the Proxy object survived intact in *both*
+ *     runs) or (b) a concrete literal byte-identical across both runs. This is a
+ *     defense-in-depth layer behind the coercion ledger.
+ *  4. **Consumed-field check.** A placeholder field that the callback *accessed*
+ *     but that never reached the recorded output — e.g. `(p.role === 'admin') ?
+ *     'A' : 'B'`, where `===` does **not** coerce (so the ledger does not fire),
+ *     the comparison is `false`, and only a literal is emitted — is rejected: the
+ *     param was silently dropped and a branch burned into the spec. (Same
+ *     consumed-field accounting #42 uses for `kind === 'admin' ? … : …`.)
+ *
+ * Arbitrary JS, reads, value branching, arithmetic, coercion, or string
+ * transforms on a param / element placeholder are therefore rejected at build
+ * time, in **both** key and value positions — **never silently emitted as a
+ * wrong spec**. Unlike key positions, value positions have **no residual class**:
+ * because a faithful value ref is never coerced, even an identity-shaped
+ * transform (`String(p.x).slice(0)`, `.normalize()`, `.trim()`, `.replace('§',…)`
+ * on an absent substring) is rejected (it coerced the ref). The only operations
+ * that *do not* coerce a ref are (a) storing it directly and (b) the brand read;
+ * (a) is the supported faithful reference and (b) is internal — so the ledger has
+ * no false positives and no escape.
+ */
+
+declare const TX_REF_BRAND: unique symbol;
+/**
+ * A captured reference to a parameter (`{name}`) or a `forEach` element field
+ * (`{item.<field>}`). Branded so the planner can distinguish a reference from a
+ * concrete literal, and so a stray reference cannot be silently coerced.
+ */
+interface TransactionRef {
+    readonly [TX_REF_BRAND]: true;
+    /** The template token this reference renders to, e.g. `{groupId}`. */
+    readonly token: string;
+    /** Human-readable origin (for error messages), e.g. `param 'groupId'`. */
+    readonly origin: string;
+}
+/** Runtime guard: is `value` a {@link TransactionRef}? */
+declare function isTransactionRef(value: unknown): value is TransactionRef;
+/** A declarative comparison used by `when` (the only branching allowed). */
+type WhenComparison = {
+    readonly op: 'eq';
+    readonly left: TransactionRef;
+    readonly right: unknown;
+} | {
+    readonly op: 'ne';
+    readonly left: TransactionRef;
+    readonly right: unknown;
+};
+/**
+ * A single captured instruction inside a transaction. The three write operations
+ * (`put` / `update` / `delete`) mutate an item; `conditionCheck` (issue #81) is a
+ * **read-only assertion** on another keyed item — it carries a `key` and a
+ * **required** `condition` and never mutates, but its failure rolls the whole
+ * transaction back. It is the foundation for referential-integrity derivation
+ * (`requires <Entity> exists` → a `conditionCheck` with `attributeExists`).
+ */
+interface TxWriteInstruction {
+    readonly kind: 'write';
+    readonly operation: 'put' | 'update' | 'delete' | 'conditionCheck';
+    readonly entity: EntityRef;
+    /** Put: the item structure (field → ref / literal). */
+    readonly item?: Record<string, unknown>;
+    /** Update / delete / conditionCheck: the key structure. */
+    readonly key?: Record<string, unknown>;
+    /** Update: the changes structure. */
+    readonly changes?: Record<string, unknown>;
+    /**
+     * The write / assertion condition (subset). Optional on `put` / `update` /
+     * `delete`; **required** on a `conditionCheck` (the assertion it makes).
+     */
+    readonly condition?: ConditionInput;
+    /** Optional declarative guard (skip this item when it does not hold). */
+    readonly when?: WhenComparison;
+}
+/** A `forEach` block expanding `body` once per element of an array param. */
+interface TxForEachInstruction {
+    readonly kind: 'forEach';
+    /** The array-param name iterated. */
+    readonly source: string;
+    /** Optional per-element declarative guard. */
+    readonly when?: WhenComparison;
+    /** The (write-only) instructions emitted per element. */
+    readonly body: TxWriteInstruction[];
+}
+type TxInstruction = TxWriteInstruction | TxForEachInstruction;
+/** Options accepted by `tx.put/update/delete`. */
+interface TxWriteOptions {
+    readonly condition?: ConditionInput;
+    readonly when?: WhenComparison;
+}
+/**
+ * Options accepted by `tx.conditionCheck` (issue #81). The `condition` is the
+ * read-only assertion the check makes against the keyed item and is **required**
+ * — a ConditionCheck with no condition is meaningless. An optional `when` skips
+ * the check entirely when the guard does not hold.
+ */
+interface TxConditionCheckOptions {
+    readonly condition: ConditionInput;
+    readonly when?: WhenComparison;
+}
+/** Options accepted by `tx.forEach`. */
+interface TxForEachOptions {
+    readonly when?: WhenComparison;
+}
+/** A small comparison helper: `when.eq(ref, value)` / `when.ne(ref, value)`. */
+declare const when: {
+    readonly eq: (left: TransactionRef, right: unknown) => WhenComparison;
+    readonly ne: (left: TransactionRef, right: unknown) => WhenComparison;
+};
+/** The transaction recorder handed to the callback as `tx`. */
+interface TxRecorder {
+    put(model: ModelStatic<DDBModel>, item: Record<string, unknown>, options?: TxWriteOptions): void;
+    update(model: ModelStatic<DDBModel>, key: Record<string, unknown>, changes: Record<string, unknown>, options?: TxWriteOptions): void;
+    delete(model: ModelStatic<DDBModel>, key: Record<string, unknown>, options?: TxWriteOptions): void;
+    /**
+     * Record a **read-only** `ConditionCheck` assertion on a keyed item (issue
+     * #81): the item is not mutated, but `options.condition` must hold or the whole
+     * transaction is cancelled atomically. The foundation for referential-integrity
+     * derivation (`requires <Entity> exists` → `conditionCheck(Model, key, {
+     * condition: { attributeExists: 'PK' } })`).
+     */
+    conditionCheck(model: ModelStatic<DDBModel>, key: Record<string, unknown>, options: TxConditionCheckOptions): void;
+    forEach<E>(source: E, body: (element: ElementProxy<E>) => void, options?: TxForEachOptions): void;
+}
+/** The element proxy type inside a `forEach` body (fields → refs). */
+type ElementProxy<E> = E extends Param<infer T> ? T extends (infer Item)[] ? {
+    readonly [K in keyof Item]: TransactionRef;
+} : never : never;
+/** The typed IR node produced by {@link defineTransaction}. */
+interface TransactionDefinition {
+    /** @internal Marks this object as a transaction definition IR node. */
+    readonly __isTransactionDefinition: true;
+    /** Collected parameters: name → descriptor (array params carry `element`). */
+    readonly params: Readonly<Record<string, ParamDescriptor>>;
+    /** The captured, declarative instruction list. */
+    readonly instructions: readonly TxInstruction[];
+}
+/** A param map accepted by {@link defineTransaction}. */
+type TransactionParamShape = Record<string, Param<unknown>>;
+/** The `p` proxy type: each scalar param → ref; each array param → itself. */
+type ParamProxy<P extends TransactionParamShape> = {
+    readonly [K in keyof P]: P[K] extends {
+        readonly kind: 'array';
+    } ? P[K] : TransactionRef;
+};
+/**
+ * Define a declarative transaction. The callback is evaluated **twice** with
+ * throwing value sentinels (one differential marker set per pass); its `tx.*`
+ * calls are recorded and the two passes are checked against each other so any
+ * non-declarative value (a transform, a value branch, a coercion escape) is
+ * rejected at build time — the same soundness #42 enforces for key positions.
+ *
+ * @param params A record of `param.*` placeholders (scalars and/or `param.array`).
+ * @param build  `(tx, p) => void` — records the write instructions.
+ */
+declare function defineTransaction<const P extends TransactionParamShape>(params: P, build: (tx: TxRecorder, p: ParamProxy<P>) => void): TransactionDefinition;
+/**
+ * Group a record of transaction definitions into the IR consumed by the static
+ * planner (#42/#46). Validates each entry is a transaction definition.
+ */
+declare function defineTransactions<const D extends Record<string, TransactionDefinition>>(definitions: D): D;
+
+/**
+ * Contract-layer serialization (issue #59, CQRS Contract layer, Epic #57;
+ * spec `docs/cqrs-contract.md`, "SSoT Schema").
+ *
+ * The Contract IR (#58, `src/define/contract.ts`) holds, per contract method, a
+ * resolved declarative {@link ContractMethodOp} plus the **decided facts** the
+ * planner derived (`resolution` / `inputArity` / `result`). This module
+ * **serializes** those facts into the JSON SSoT — it does **not** re-derive them:
+ *
+ * - The `contracts` map (contract name → {@link ContractSpec}) is layered **on
+ *   top of** the existing `queries` / `commands` / `transactions`. Each method
+ *   references one of them by name (`ContractName__methodName`), so the existing
+ *   operation-spec shapes are unchanged and the current runtime keeps working.
+ * - The referenced operation spec is produced by **reusing** the proven
+ *   {@link buildQuerySpec} / {@link buildCommandSpec} planners: a
+ *   {@link ContractMethodOp} is translated back into the {@link AnyOperationDefinition}
+ *   shape those planners consume (the contract's sentinel references become the
+ *   `Param` placeholders the planner already understands), so the symbolic key
+ *   evaluation, projection, relation chaining, and condition handling are shared
+ *   — never re-implemented, never drifting.
+ *
+ * Everything emitted is **JSON-serializable** by construction (only strings /
+ * numbers / booleans / arrays / plain objects). A contract-free input emits no
+ * `contracts` / `contexts` keys, so the pre-#59 operations document is reproduced
+ * byte-for-byte (backward compatibility).
+ *
+ * ## What this issue serializes vs. defers
+ *
+ * The #58 IR captures a single declarative op per method with a boolean `select`
+ * projection; it does **not** model External Query / Query Composition (no
+ * `query(Contract.method, { from(...) })` primitive exists yet). So no #58
+ * contract produces a `compose`. The serializer nonetheless **supports** it: when
+ * a method op carries composition (a forward-compatible {@link ContractMethodOp}
+ * extension), it is emitted per the proposal's `compose` shape. The N+1 checker
+ * (#60), boundary lint (#61), and runtime execution (#62) are out of scope here —
+ * this is serialization + generator only.
+ */
+
+/**
+ * A contract as accepted by the serializer: either a resolved
+ * {@link QueryModelContract} or a {@link CommandModelContract} (the #58 factory
+ * output). The Key type is erased — the serializer reads the key **fields** off
+ * the resolved op / model metadata, not the phantom type.
+ */
+type AnyModelContract = QueryModelContract<unknown, Record<string, QueryMethodSpec<unknown, unknown, unknown>>> | CommandModelContract<unknown, Record<string, CommandMethodSpec<unknown, unknown, unknown>>>;
+/** A map of contract name → resolved contract IR (as passed to the generator). */
+type ContractMap = Record<string, AnyModelContract>;
+/**
+ * A context-ownership declaration as authored by the producer: context name →
+ * the Model (entity) and Contract names that belong to it. The serializer sorts
+ * the member lists deterministically; see {@link ContextSpec}.
+ */
+interface ContextOwnership {
+    readonly models?: readonly string[];
+    readonly contracts?: readonly string[];
+}
+/** A map of context name → its membership (as passed to the generator). */
+type ContextOwnershipMap = Record<string, ContextOwnership>;
+/**
+ * The output of {@link buildContracts}: the `contracts` map and the
+ * **synthesized** operation specs each method references. The caller merges the
+ * synthesized `queries` / `commands` / `transactions` into the document's
+ * existing maps (a contract method's referenced op lives alongside hand-written
+ * definitions, addressed by name).
+ */
+interface BuiltContracts {
+    readonly contracts: Record<string, ContractSpec>;
+    /** Synthesized read ops referenced by query contract methods. */
+    readonly queries: Record<string, QuerySpec>;
+    /** Synthesized write ops referenced by command contract methods (single form). */
+    readonly commands: Record<string, CommandSpec>;
+    /**
+     * Synthesized transactions referenced by command contract methods whose array
+     * form resolves to a `'transact'` batched write (issue #64). One transaction per
+     * such method, named `<Contract>__<method>__batch`: a single `forEach`-over-keys
+     * write item that the runtime expands once per key (≤25, atomic), reusing the
+     * proven declarative-transaction machinery (#46). Empty when no command method
+     * declares a `'transact'` batch.
+     */
+    readonly transactions: Record<string, TransactionSpec>;
+}
+/**
+ * Serialize a map of resolved contracts into the `contracts` SSoT map plus the
+ * synthesized operation specs each method references. Deterministic: contracts
+ * and methods are emitted in sorted-key order.
+ *
+ * @param contracts Contract name → resolved {@link QueryModelContract} /
+ *   {@link CommandModelContract} (the #58 factory output). Empty → empty output.
+ * @throws if a contract method op cannot be serialized (a non-boolean projection
+ *   slot, an unsupported write condition); or if a contract violates an N+1
+ *   safety rule (#60, {@link assertContractN1Safe}) — an array into a `range`
+ *   method, a "list under a list", or a `range` composed child.
+ */
+declare function buildContracts(contracts?: ContractMap): BuiltContracts;
+/**
+ * Serialize the context-ownership declarations into the SSoT `contexts` map.
+ * Member lists are sorted for determinism. An empty input yields an empty map
+ * (the caller then omits the key for backward compatibility).
+ */
+declare function buildContexts(contexts?: ContextOwnershipMap): Record<string, ContextSpec>;
+
+/**
+ * Static parameterized operation-spec generation (issue #42, Phase 0b).
+ *
+ * Turns the parameterized definition IR (#41) into JSON-serializable
+ * {@link OperationSpec} / {@link CommandSpec} via **symbolic evaluation** of the
+ * key / GSI mapping functions. The result is deterministic and contains only
+ * `{param}` / `{result.field}` template placeholders, never concrete values.
+ *
+ * Relation chains in a read `select` become **multiple operations** wired with
+ * `resultPath` and `{result.*}` key templates, mirroring the runtime
+ * `relation-planner` policy: `hasMany` → `Query` + `begins_with`, `belongsTo` /
+ * `hasOne` → `BatchGetItem`.
+ */
+
+/** Build the {@link QuerySpec} for a single read definition. */
+declare function buildQuerySpec(def: AnyOperationDefinition): QuerySpec;
+/**
+ * Optional contract-layer inputs to {@link buildOperations} (issue #59). Both are
+ * absent on a pre-#59 (contract-free) build, in which case the produced document
+ * is byte-identical to the pre-#59 shape (no `contracts` / `contexts` keys).
+ */
+interface ContractInputs {
+    /** Resolved contracts (publicQueryModel / publicCommandModel output). */
+    readonly contracts?: ContractMap;
+    /** Context-ownership declarations (context → member models / contracts). */
+    readonly contexts?: ContextOwnershipMap;
+}
+/**
+ * Build the operations document from grouped read (`queries`) and write
+ * (`commands`) definition maps, plus the optional CQRS contract layer (#59).
+ * All inputs are optional. Output is deterministic (definitions emitted in
+ * sorted-key order; the runtime resolves by name).
+ *
+ * The contract layer (#59) is layered **on top of** the existing specs: each
+ * contract method's underlying op is synthesized into `queries` / `commands` and
+ * referenced by name, and the `contracts` / `contexts` maps are emitted. A
+ * contract-free input (`contractInputs` empty / absent) reproduces the pre-#59
+ * document byte-for-byte — no `contracts` / `contexts` keys appear.
+ *
+ * @throws if a command carries a write condition outside the supported subset
+ *   (`{ notExists }` or pure equality) — the bridge guard; or if a contract op
+ *   name collides with a hand-written definition.
+ */
+declare function buildOperations(queries?: DefinitionMap, commands?: DefinitionMap, transactions?: Record<string, TransactionDefinition>, contractInputs?: ContractInputs): OperationsDocument;
+
+/**
+ * Manifest generation (issue #42, Python-bridge Phase 0b).
+ *
+ * Produces the JSON-serializable {@link Manifest} from a {@link MetadataRegistry}
+ * snapshot: entity → table / physicalName / prefix / field types / key & GSI
+ * templates / relation metadata. Generation is **deterministic** — entities,
+ * fields, GSIs, and relations are emitted in a stable (sorted) order so the same
+ * registry always yields byte-identical JSON.
+ */
+
+/**
+ * Build the full {@link Manifest} from the {@link MetadataRegistry}.
+ *
+ * Every registered entity is included. Output ordering is deterministic
+ * (entities / fields / relations sorted by name, GSIs by index name).
+ */
+declare function buildManifest(registry?: typeof MetadataRegistry): Manifest;
+
+/**
+ * N+1 static checker for the CQRS Contract layer (issue #60, Epic #57; proposal
+ * `docs/cqrs-contract.md`, "N+1 Safety (Static Restriction)").
+ *
+ * Whether a resolution is N+1-safe depends on **two** facts the planner already
+ * decided in #58 and #59 serialized into the SSoT — the checker **honors** them,
+ * it does **not** re-derive policy ("decide once, declare in the SSoT"):
+ *
+ * - `resolution` — `'point'` (target keys known → `BatchGetItem` / another
+ *   contract's `get(keys[])`; coalesces) or `'range'` (target key set unknown →
+ *   partition `Query`; one request per partition key).
+ * - `inputArity` / parent `cardinality` — how many keys are fed in. A `range`
+ *   method is one query for one key but N queries for N keys.
+ *
+ * The rule (absolute, no opt-in escape hatch): **a `range` resolution is allowed
+ * only with single-key input.** Three forms are build-time errors:
+ *
+ *  (a) **array into a `range` method** — a `range` method whose `inputArity` is
+ *      not `'single'` (`'array'` / `'either'`). A `range` method must be
+ *      `'single'`; anything else is an N partition-`Query` fan-out.
+ *  (a′) **array into a unique-GSI `point` method** (issue #71) — a `point` method
+ *      whose Key resolves via a **unique GSI** (a per-key `Query`, since
+ *      `BatchGetItem` cannot read a GSI) but whose `inputArity` is not `'single'`.
+ *      A base-table `point` coalesces a key array into one `BatchGetItem`, but a
+ *      unique-GSI `point` would issue N `Query`s — an N+1 fan-out, the same shape
+ *      as (a). graphddb's official spec does not include N+1-producing queries, so
+ *      it is rejected at build time; the application-side loop is the escape (same
+ *      philosophy as `range`).
+ *  (b) **"list under a list"** — a `range` child nested under a parent step whose
+ *      output cardinality is `'many'`. The composition's parent yields N records,
+ *      so a `range` child fans out to N partition `Query`s.
+ *  (c) **`compose` child that is `range`** — the cross-contract / composition form
+ *      of (b): a composed (External Query) child declared `range` under a parent
+ *      that can yield many. (Rule (b) and (c) are the same axis — a `range` child
+ *      under a many-yielding parent — surfaced through nested model relations vs.
+ *      cross-contract composition respectively.)
+ *
+ * `point` resolutions are always allowed (they coalesce). If a caller genuinely
+ * needs "just these few", it loops in its own application code (the proposal's
+ * `Promise.all(ids.map(...))`), keeping the N visible at the call site —
+ * the contract surface never hides a fan-out.
+ *
+ * ## Placement — build path, not the model `LintRule` framework
+ *
+ * This checker runs on the **contract build path** ({@link buildContracts} in
+ * `src/spec/contracts.ts`), where every other contract validation surfaces
+ * (#59's projection audit, write-condition guard, and the original inline
+ * `compose` rule all `throw` there). It operates on the serialized
+ * {@link ContractSpec} facts, not on {@link EntityMetadata}: the existing
+ * `src/linter/` `LintRule` framework is keyed on a single model's `EntityMetadata`
+ * (model relations / GSIs), which carries none of the contract `resolution` /
+ * `inputArity` / `compose` facts the N+1 rule needs. Surfacing the violation as a
+ * thrown build error — exactly as `relation/traversal.ts` `validateDepth` and the
+ * #59 contract validations do — fails the build the same way `inputArity`
+ * mismatches and `range` composed children already failed it.
+ *
+ * The cross-contract `range`-child form (c) and the nested-relation form (b) are
+ * only fully reachable once the composition DSL primitive
+ * (`query(Contract.method, { from() })`, owned by #63) lands; until then no #58
+ * DSL produces a `compose` node. The checker implements the full logic now so it
+ * is ready, and the forward forms are exercised by feeding synthesized SSoT nodes
+ * (exactly as #59's serializer tests do).
+ */
+
+/** A single N+1 rule violation, carrying the rule label and a clear message. */
+interface ContractN1Violation {
+    /** Which of the N+1 forms was violated. */
+    readonly rule: 'array-into-range' | 'array-into-gsi-point' | 'list-under-list' | 'compose-range-under-many';
+    /** The offending contract name. */
+    readonly contract: string;
+    /** The offending method name. */
+    readonly method: string;
+    /** A clear, actionable error message (the same text the thrown error carries). */
+    readonly message: string;
+}
+/**
+ * Tells, for a query contract method name, whether its `point` read resolves via
+ * a **unique GSI** (a per-key `Query`) rather than the base-table primary key (a
+ * coalescible `GetItem` / `BatchGetItem`). Supplied by the serializer (issue #71),
+ * which recovers the fact from the method's synthesized read op (a root `Query`
+ * carrying an `indexName`). Absent → no method is treated as a GSI point (the
+ * pre-#71 default; e.g. synthesized-SSoT checker tests that exercise only the
+ * `range` / `compose` rules).
+ */
+type IsGsiPointMethod = (methodName: string) => boolean;
+/**
+ * Collect every N+1 violation in a single serialized {@link ContractSpec}.
+ * Command contracts carry no `resolution` / `compose` and are always N+1-safe
+ * (writes resolve to known keys), so only query contracts are inspected.
+ *
+ * @param isGsiPoint Optional predicate (issue #71): does the named method's
+ *   `point` read resolve via a unique GSI? Used to reject array-into-GSI-point
+ *   (rule a′). Defaults to "never" when not supplied.
+ */
+declare function collectContractN1Violations(contractName: string, spec: ContractSpec, isGsiPoint?: IsGsiPointMethod): ContractN1Violation[];
+/**
+ * Assert a single serialized contract is N+1-safe, throwing the first violation
+ * as a build error (mirroring `relation/traversal.ts` `validateDepth` and the
+ * #59 contract validations, which `throw` on the build path). Multiple violations
+ * are summarized in the thrown message so the build surfaces them all at once.
+ *
+ * @throws if any of the N+1 forms is present.
+ *
+ * @param isGsiPoint Optional predicate (issue #71) identifying unique-GSI `point`
+ *   methods, so rule (a′) (array into a GSI point) can be enforced.
+ */
+declare function assertContractN1Safe(contractName: string, spec: ContractSpec, isGsiPoint?: IsGsiPointMethod): void;
+
+/**
+ * Bounded-context boundary checker for the CQRS Contract layer (issue #61, Epic
+ * #57; spec `docs/cqrs-contract.md`, External Query section "Why it
+ * exists: boundary enforcement").
+ *
+ * The rule, stated in the proposal and the issue: a **Model is a private
+ * implementation detail of its bounded context; a Contract is the published
+ * interface**. Within its own context a contract resolves its own Models directly
+ * (internal `query` / `list` / `put` / `update` / `delete`). Across a context
+ * boundary it may depend on another context **only through that context's
+ * published Contract** (an External Query / Command). Reaching directly into a
+ * **foreign** Model is a **build-time error** — it couples one context to
+ * another's private storage shape and silently defeats the boundary the contexts
+ * declaration is meant to enforce.
+ *
+ * ## What "own" vs. "foreign" means here
+ *
+ * The decision is made entirely from the **context-ownership declaration** (#59,
+ * the `contexts` map: context name → `{ models, contracts }`). For each contract:
+ *
+ *  - its **owning context** is the (unique) context whose `contracts` list names
+ *    it; and
+ *  - for every Model its method ops touch (the recorded {@link ContractMethodOp}
+ *    `entity` refs, #58), that Model's **owning context** is the context whose
+ *    `models` list names it.
+ *
+ * A method op against a Model owned by a **different** context than the contract's
+ * own is the violation. Three cases are deliberately **allowed**, never flagged:
+ *
+ *  - the Model and the contract are in the **same** context (the normal internal
+ *    case);
+ *  - the **contract is in no declared context** — there is no boundary to enforce
+ *    *from*, so the contract is unconstrained (a partial / incremental adoption of
+ *    the contexts declaration must not turn unrelated contracts into errors);
+ *  - the touched **Model is in no declared context** — an undeclared Model has no
+ *    owner to protect, so it is not "foreign" to anyone. (Declaring the Model into
+ *    a context is what opts it into boundary protection.)
+ *
+ * In short: the check fires **only** when both the contract *and* the foreign
+ * Model have declared, *different* owners. This is the least-surprising reading of
+ * a *partial* contexts declaration and keeps the rule purely additive — declaring
+ * more ownership can only ever surface *more* violations, never fewer.
+ *
+ * ## Placement — build path, not the model `LintRule` framework (decision B)
+ *
+ * This checker runs in **{@link buildOperations}** (`src/spec/operations.ts`),
+ * immediately before the {@link buildContracts} call — the seam where both the
+ * raw contract IR (the recorded op `entity` refs) and the `contexts` map are
+ * still available, alongside #59's projection audit, the write-condition guard,
+ * and #60's N+1 checker — every contract validation surfaces there as a thrown
+ * build error. It is **not** added to the `src/linter/` `LintRule`
+ * framework, even though the issue text suggests a `context-boundary` rule there,
+ * because that framework's contract — `check(metadata: EntityMetadata, registry)`
+ * — is keyed on a **single model's** {@link EntityMetadata} and carries **none** of
+ * the facts this rule needs:
+ *
+ *  - which context a *contract* belongs to (a contract is not an `EntityMetadata`);
+ *  - which Models a contract's *methods* touch (these live on the unserialized
+ *    {@link ContractMethodOp} `entity` refs, not on any model's metadata);
+ *  - the cross-cutting `contexts` map relating the two.
+ *
+ * A `LintRule` sees one model at a time and no contract facts at all, so a naive
+ * rule physically cannot observe a contract→foreign-Model reference. Bending the
+ * framework to carry contracts + contexts would be an invasive, parallel
+ * "rule kind" that no other rule uses — exactly the ugly refactor the brief warns
+ * against. Placing the check here is consistent with how #60 already resolved the
+ * identical tension (`src/spec/contract-n1-check.ts`, "Placement"), and it reads
+ * the **same facts the rule actually depends on** at the one point where contracts
+ * and contexts are both in hand. The boundary violation fails the build the same
+ * way an `inputArity` mismatch or a `range` composed child already does.
+ */
+
+/** A single context-boundary violation, carrying the offending facts + message. */
+interface ContractBoundaryViolation {
+    /** The offending contract name. */
+    readonly contract: string;
+    /** The context that owns the offending contract. */
+    readonly contractContext: string;
+    /** The contract method whose op touched the foreign Model. */
+    readonly method: string;
+    /** The foreign Model (entity / model-class name) referenced directly. */
+    readonly foreignModel: string;
+    /** The context that owns the foreign Model. */
+    readonly foreignContext: string;
+    /** A clear, actionable error message (the same text the thrown error carries). */
+    readonly message: string;
+}
+/**
+ * Collect every context-boundary violation across a map of resolved contracts,
+ * given the context-ownership declaration. A violation is a contract method whose
+ * recorded op touches a Model owned by a **different** context than the contract's
+ * own (see the module doc for the precise own / foreign / undeclared rule).
+ *
+ * @param contracts Contract name → resolved {@link QueryModelContract} /
+ *   {@link CommandModelContract} (the #58 factory output).
+ * @param contexts  The context-ownership declaration (#59). When empty, no
+ *   contract has a declared owner, so there are no boundaries to enforce → no
+ *   violations.
+ * @throws if the contexts declaration claims a Model / Contract in two contexts
+ *   (an ambiguous, self-contradictory declaration).
+ */
+declare function collectContractBoundaryViolations(contracts: ContractMap, contexts: ContextOwnershipMap): ContractBoundaryViolation[];
+/**
+ * Assert a map of resolved contracts respects bounded-context boundaries, throwing
+ * the first violation as a build error (mirroring #60's {@link assertContractN1Safe}
+ * and the other #59 contract validations, which `throw` on the build path).
+ * Multiple violations are summarized in the thrown message so the build surfaces
+ * them all at once.
+ *
+ * @param contracts Contract name → resolved contract IR.
+ * @param contexts  The context-ownership declaration (#59).
+ * @throws if any contract directly references a foreign context's Model, or if the
+ *   contexts declaration is ambiguous (a Model / Contract claimed twice).
+ */
+declare function assertContractBoundaries(contracts: ContractMap, contexts: ContextOwnershipMap): void;
+
+/**
+ * Static planning for declarative transactions (issue #46, Phase 4).
+ *
+ * Turns a {@link TransactionDefinition} (captured by `defineTransaction`) into a
+ * serializable {@link TransactionSpec}. Each `tx.put/update/delete` becomes a
+ * templated {@link TransactionItemSpec}; a `tx.forEach` block marks its items
+ * with a `forEach` binding so the runtime expands them once per array-param
+ * element. Key templates are derived with the **same** symbolic key-mapping
+ * evaluator (#42 `evaluateKey`) the single-write planner uses — the
+ * declarativity of the field references is what lets that reuse work: every
+ * key / item / changes leaf is either a field reference (whose token the planner
+ * substitutes) or a concrete literal.
+ */
+
+/** Build the {@link TransactionSpec} for one transaction definition. */
+declare function buildTransactionSpec(txName: string, def: TransactionDefinition): TransactionSpec;
+/** Build the transactions map from a record of transaction definitions. */
+declare function buildTransactions(transactions?: Record<string, TransactionDefinition>): Record<string, TransactionSpec>;
+
+/**
+ * Bridge guard (issue #42, Phase 0b).
+ *
+ * The Python bridge can only carry a **declarative, serializable subset** of
+ * graphddb. This module enforces that subset at build time:
+ *
+ * 1. **Write conditions** must be `{ notExists }`, an existence primitive
+ *    (`{ attributeExists }` / `{ attributeNotExists }` on any field, issue #81),
+ *    *or* pure field equality (mirroring `expression/condition-expression.ts`,
+ *    which only emits `attribute_(not_)exists(...)` or `#f = :v` clauses). Any
+ *    other condition shape is rejected — there is no serializable representation
+ *    for it. {@link conditionInputToSpec} is the single place the IR-shaped input
+ *    is mapped to the {@link ConditionSpec} subset.
+ * 2. The produced bundle must be **JSON-serializable** — no functions, classes,
+ *    `Date`, `Set`, `Map`, `Symbol`, or non-finite numbers may leak into the
+ *    spec. {@link assertJsonSerializable} walks the value and throws on any.
+ *
+ * (Note: the post-load TS predicate `refine` was removed in #49, so no guard for
+ * it is needed; see `docs/python-bridge.md`.)
+ */
+
+/**
+ * Assert a write {@link ConditionSpec} is within the supported subset. The spec
+ * type already constrains it to `notExists` | `attributeExists` |
+ * `attributeNotExists` | `equals`, so this defends against a malformed `equals`
+ * (empty / non-template values) or a blank existence field and gives a clear,
+ * single-source build-time error message for any future widening.
+ */
+declare function assertSupportedCondition(commandName: string, condition: ConditionSpec): void;
+/**
+ * Walk an arbitrary value and throw if it contains anything that does not
+ * survive `JSON.stringify` round-tripping as itself (functions, symbols,
+ * `undefined`, `Date`, `Map`, `Set`, class instances, non-finite numbers).
+ */
+declare function assertJsonSerializable(value: unknown, path?: string): void;
+/** Convenience: assert an entire {@link BridgeBundle} is JSON-serializable. */
+declare function assertBundleSerializable(bundle: BridgeBundle): void;
+
+/**
+ * Static parameterized planner: serializable OperationSpec + manifest + bridge
+ * guard (issue #42, Python-bridge Phase 0b). Public surface.
+ *
+ * The CLI / file output is #43's responsibility; this module stops at the
+ * **generation functions** producing the typed, JSON-serializable
+ * `{ manifest, operations }` bundle.
+ */
+
+/**
+ * Build the full `{ manifest, operations }` bridge bundle from grouped query /
+ * command definition maps. The bundle is typed and JSON-serializable; the bridge
+ * guard runs (unsupported write conditions throw during `buildOperations`, and
+ * the whole bundle is asserted JSON-serializable here).
+ *
+ * @param queries  Read definitions (`defineQueries(...)` output). Optional.
+ * @param commands Write definitions (`defineCommands(...)` output). Optional.
+ * @param registry Metadata source (defaults to the global registry).
+ * @param transactions Declarative transactions (`defineTransactions(...)`). Optional.
+ * @param contractInputs The CQRS contract layer (#59): resolved contracts +
+ *   context-ownership. Optional — absent reproduces the pre-#59 document.
+ */
+declare function buildBridgeBundle(queries?: DefinitionMap, commands?: DefinitionMap, registry?: typeof MetadataRegistry, transactions?: Record<string, TransactionDefinition>, contractInputs?: ContractInputs): BridgeBundle;
+
+export { type AnyModelContract as A, type BuiltContracts as B, type ContextOwnership as C, buildTransactions as D, collectContractBoundaryViolations as E, collectContractN1Violations as F, defineTransaction as G, defineTransactions as H, isTransactionRef as I, when as J, type TransactionDefinition as T, type WhenComparison as W, type ContextOwnershipMap as a, type ContractBoundaryViolation as b, type ContractInputs as c, type ContractMap as d, type ContractN1Violation as e, type TransactionParamShape as f, type TransactionRef as g, type TxConditionCheckOptions as h, type TxForEachInstruction as i, type TxForEachOptions as j, type TxInstruction as k, type TxRecorder as l, type TxWriteInstruction as m, type TxWriteOptions as n, assertBundleSerializable as o, assertContractBoundaries as p, assertContractN1Safe as q, assertJsonSerializable as r, assertSupportedCondition as s, buildBridgeBundle as t, buildContexts as u, buildContracts as v, buildManifest as w, buildOperations as x, buildQuerySpec as y, buildTransactionSpec as z };