graphddb 0.7.9 → 0.8.0

package/dist/spec/index.d.ts

@@ -1,4 +1,506 @@
-export { a1 as BridgeBundle, a4 as CommandContractMethodSpec, a5 as CommandResolutionTarget, H as CommandSpec, a6 as CompiledFragment, a7 as CompiledMutationPlan, a8 as ComposeSpec, a9 as CompositionPlanSpec, a2 as ConditionSpec, J as ContextSpec, aa as ContractCardinality, ab as ContractCommandResult, ac as ContractInputArity, ad as ContractKeySpec, ae as ContractKind, af as ContractResolution, A as ContractSpec, ag as DerivedConditionCheck, ah as DerivedEdgeWrite, ai as DerivedIdempotencyGuard, aj as DerivedMaintainOutbox, ak as DerivedMaintainWrite, al as DerivedOutboxEvent, am as DerivedUniqueGuard, an as DerivedUpdate, ao as EntityRefResolver, ap as ExecutionPlanSpec, aq as FilterSpec, ar as MAX_TRANSACT_COMPOSE_ITEMS, a0 as Manifest, as as ManifestEntity, at as ManifestField, au as ManifestFieldType, av as ManifestGsi, aw as ManifestKey, ax as ManifestRelation, ay as ManifestTable, az as OperationSpec, _ as OperationsDocument, L as ParamSpec, aA as QueryContractMethodSpec, G as QuerySpec, aB as RangeConditionSpec, aC as ReadOperationType, K as SPEC_VERSION, aD as TransactionItemSpec, aE as TransactionItemType, I as TransactionSpec, aF as WhenSpec, aG as WriteOperationType, aH as assertNoCrossFragmentMaintainCollision, aI as compileFragment, aJ as compileMutationPlan, aK as compileSingleFragmentPlan, aL as resetMaintenanceGraphCache, aM as resolveLifecycle, aN as resolveMaintainers } from '../maintenance-view-adapter-BATUh_I8.js';
-export { A as AnyModelContract, B as BuiltContracts, C as ContextOwnership, b as ContextOwnershipMap, c as ContractBoundaryViolation, d as ContractInputs, e as ContractMap, f as ContractN1Violation, O as PREPARED_FORMAT_VERSION, Q as PreparedBindMap, g as PreparedBindSpec, a as PreparedPlanDocument, h as PreparedPlanSpec, i as PreparedReadRouteSpec, P as PreparedWriteOpSpec, s as assertBundleSerializable, t as assertContractBoundaries, u as assertContractN1Safe, v as assertJsonSerializable, w as assertSupportedCondition, x as buildBridgeBundle, y as buildContexts, z as buildContracts, D as buildManifest, E as buildOperations, R as buildPreparedPlanDocument, F as buildQuerySpec, G as buildTransactionSpec, H as buildTransactions, S as canonicalJson, I as collectContractBoundaryViolations, J as collectContractN1Violations, U as compilePreparedPlan, V as entityFingerprint, X as planFingerprint } from '../index-CtPJSMrc.js';
-import '../registry-CXhP4TaE.js';
-import '@aws-sdk/client-dynamodb';
+import { $ as AnyOperationDefinition, a0 as TransactionDefinition, b as PreparedBody } from '../key-DR7_lpyk.js';
+export { a1 as CompiledFragment, a2 as CompiledMutationPlan, a3 as DerivedConditionCheck, a4 as DerivedEdgeWrite, a5 as DerivedIdempotencyGuard, a6 as DerivedMaintainOutbox, a7 as DerivedMaintainWrite, a8 as DerivedOutboxEvent, a9 as DerivedUniqueGuard, aa as DerivedUpdate, ab as EntityRefResolver, ac as MAX_TRANSACT_COMPOSE_ITEMS, ad as assertNoCrossFragmentMaintainCollision, ae as compileFragment, af as compileMutationPlan, ag as compileSingleFragmentPlan, ah as resetMaintenanceGraphCache, ai as resolveLifecycle, aj as resolveMaintainers } from '../key-DR7_lpyk.js';
+import { M as MetadataRegistry } from '../linter-C-vypgut.js';
+import { C as ContractMap, e as ContextOwnershipMap, c as PreparedPlanSpec, a as PreparedPlanDocument } from '../prepared-artifact-BpPgkXEo.js';
+export { A as AnyModelContract, B as BuiltContracts, f as ContextOwnership, g as PREPARED_FORMAT_VERSION, h as PreparedBindMap, b as PreparedBindSpec, d as PreparedReadRouteSpec, P as PreparedWriteOpSpec, i as buildContexts, j as buildContracts, k as canonicalJson, l as entityFingerprint, p as planFingerprint } from '../prepared-artifact-BpPgkXEo.js';
+import { O as OperationsDocument, Q as QuerySpec, M as Manifest, C as ContractSpec, T as TransactionSpec, B as BridgeBundle, c as ConditionSpec, E as ExpressionSpec, a as CommandSpec, d as SpecVersion } from '../types-2PMXEn5x.js';
+export { e as CommandContractMethodSpec, f as CommandResolutionTarget, g as ComposeSpec, h as CompositionPlanSpec, b as ContextSpec, i as ContractCardinality, j as ContractCommandResult, k as ContractInputArity, l as ContractKeySpec, m as ContractKind, n as ContractResolution, o as EXPR_VERSION, p as ExecutionPlanSpec, q as ExpressionArrNode, r as ExpressionFloatNode, s as ExpressionIntNode, t as ExpressionNode, u as ExpressionObjNode, v as ExpressionOpNode, w as ExpressionOperator, x as ExpressionRefNode, y as ExpressionRefOptNode, z as ExpressionScalar, F as FilterSpec, A as ManifestEntity, D as ManifestField, G as ManifestFieldType, H as ManifestGsi, I as ManifestKey, J as ManifestRelation, K as ManifestTable, L as OperationSpec, P as ParamSpec, N as QueryContractMethodSpec, R as RangeConditionSpec, U as ReadOperationType, S as SPEC_VERSION, V as SPEC_VERSION_SCP, W as SPEC_VERSION_SUPPORTED, X as TransactionItemSpec, Y as TransactionItemType, Z as WhenSpec, _ as WriteOperationType } from '../types-2PMXEn5x.js';
+import '../types-BXLzIcQD.js';
+
+/**
+ * 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 (publishQuery / publishCommand 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?: Record<string, AnyOperationDefinition>, commands?: Record<string, AnyOperationDefinition>, 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;
+
+/**
+ * SCP Expression IR — build-time validation + canonicalization (issue #261,
+ * Phase 3 S1; behavior-contracts `expression-ir.md` §2).
+ *
+ * This module is the spec-side **vocabulary** gate: it validates an authored
+ * expression against the closed v1 node/operator set (fail-closed — anything
+ * outside the set is a build error, never a silently-carried unknown) and
+ * rewrites it into the **canonical serialization form** of §2.3/§2.4:
+ *
+ * - object keys sorted in **Unicode code-point order** at every level
+ *   (canonical-serialization.md §2 — NOT JS default `.sort()`, which compares
+ *   UTF-16 code units and diverges on astral-plane keys);
+ * - an integer-valued JSON number within the safe range stays a plain number
+ *   (an int literal); beyond ±2^53−1 it must be `{int:"…"}` (raw is invalid);
+ * - `{int:"…"}` whose value fits the safe range canonicalizes to the plain
+ *   number; outside it stays `{int:"…"}` (must fit i64);
+ * - `{float:n}` with an integer value stays wrapped; a fractional `{float:n}`
+ *   canonicalizes to the plain number (JSON preserves its decimal part).
+ *
+ * Because the canonical form of the expression NODES is produced HERE (at
+ * build time), the documents flow through graphddb's ordinary JSON emitters
+ * unchanged — no special-cased serializer. Note the distinction: §2.3/§2.4
+ * key-sorting governs the expression nodes (`obj` construction keys; operator
+ * nodes are single-key by definition); the `{ exprVersion, expr }` ENVELOPE and
+ * the surrounding spec documents serialize in graphddb's usual emitter order
+ * like every other spec object (conformance value comparison is structural,
+ * expression-ir.md §2.4).
+ *
+ * Evaluation lives in the Phase 3 S5/S6/S7 sub-issues — this module never
+ * evaluates anything. It also hosts the conditional spec-version presence scan
+ * ({@link operationsSpecVersion}): a document that actually CONTAINS an SCP
+ * node is stamped `1.2`, everything else keeps `1.1` byte-identically.
+ */
+
+/**
+ * Validate an authored `{ exprVersion: 1, expr: <node> }` envelope against the
+ * closed v1 vocabulary and return it in canonical form (§2.3/§2.4: key-sorted,
+ * normalized `{int:"…"}` / `{float:n}` literal wrapping). Fail-closed: an
+ * unknown `exprVersion`, an extra envelope key, or any node outside the closed
+ * set is a build error with the offending path.
+ */
+declare function canonicalizeExpressionSpec(input: unknown, context: string): ExpressionSpec;
+/**
+ * Does this operations-document content actually contain an SCP Expression IR
+ * node — a `{ kind: 'scpExpr' }` write condition or a `guard` (transaction
+ * item / contract command method)? This is the **presence scan** behind the
+ * conditional stamp (issue #261): the walk visits exactly the slots the spec
+ * vocabulary defines, so an SCP-free document is provably stamped `1.1` and
+ * stays byte-identical.
+ */
+declare function operationsContainScpNodes(doc: {
+    readonly commands: Readonly<Record<string, CommandSpec>>;
+    readonly transactions?: Readonly<Record<string, TransactionSpec>>;
+    readonly contracts?: Readonly<Record<string, ContractSpec>>;
+}): boolean;
+/**
+ * The spec version to stamp on an operations document: `1.2` iff it actually
+ * contains an SCP node ({@link operationsContainScpNodes}), else the base
+ * `1.1` — so every pre-#261 bundle serializes byte-identically.
+ */
+declare function operationsSpecVersion(doc: Parameters<typeof operationsContainScpNodes>[0]): SpecVersion;
+
+/**
+ * Static prepared-plan artifact — the **build-time** (AOT) compilation of
+ * `DDBModel.prepare` bodies (issue #208; design #203 phase 4, on top of the #205
+ * runtime and the #206 compile-time hoist).
+ *
+ * `graphddb transform prepared --aot` evaluates each no-capture-verified prepare
+ * body at BUILD time (the #206 lint proves build-time evaluability) and this
+ * module compiles the evaluated routes into a JSON-serializable
+ * {@link PreparedPlanDocument}:
+ *
+ * - a **write** plan runs the SAME mutation compiler the runtime `prepare` uses
+ *   (`compileWriteFragment` → lifecycle resolution → derived-effect derivation)
+ *   and serializes the result through the SAME contract-SSoT path a
+ *   `.plan(mutation)` command method uses
+ *   ({@link serializePreparedWriteFragment} → one declarative
+ *   {@link TransactionSpec} per op: base write + edges / counters / uniqueness
+ *   guards / outbox / idempotency / maintenance / ConditionChecks) — so the
+ *   runtime never invokes the mutation compiler again, **including the first
+ *   call** (the #206 audit's cold-start gap);
+ * - a **read** plan serializes the analyzed route products (entity name, select
+ *   template, per-field param binds, static/dynamic options) plus the
+ *   {@link QuerySpec} the spec planner derives for it — the same
+ *   `operations.json` vocabulary the Python runtime consumes (templated
+ *   `{param}` key conditions, physical ops, execution plan), so a broken read
+ *   plan fails the BUILD, not the first request.
+ *
+ * ## Model references are entity NAMES
+ *
+ * The artifact never carries a class: each plan records the entity names it
+ * touches plus a **fingerprint** of each entity's canonical manifest entry
+ * ({@link entityFingerprint}). The TS loader (`src/runtime/prepared-loader.ts`)
+ * re-binds names against the live {@link MetadataRegistry} and recomputes the
+ * fingerprints — a mismatch (model declaration / TableMapping drift since the
+ * artifact was generated) is a LOUD reject, never a stale-plan execution.
+ *
+ * Everything emitted is JSON-serializable by construction (the #206 no-capture
+ * lint guarantees the body's templates are static data; the only non-JSON
+ * scalars a template may carry — `Date` / `bigint` literals — are encoded
+ * explicitly in {@link PreparedBindSpec}).
+ *
+ * ## Layering (#223)
+ *
+ * This module is BUILD-TIME ONLY. The artifact shapes, the format version, and
+ * the fingerprint/canonical-JSON helpers the runtime loader also needs live in
+ * the shared, dependency-minimal `./prepared-artifact.ts` — both this emitter
+ * and the loader (`src/runtime/prepared-loader.ts`) depend on that module, and
+ * the loader NEVER imports this one (a loader→emitter import leaks the whole
+ * build-time spec machinery into the runtime bundle — the #223 size-limit
+ * failure). The shared symbols are re-exported here for API continuity.
+ */
+
+/**
+ * Compile ONE `DDBModel.prepare` body into its static {@link PreparedPlanSpec}
+ * (build-time). The body is evaluated once with the recording `$` proxy — the
+ * #206 no-capture lint has already proven this is side-effect-free and
+ * params-independent — then each route is analyzed and serialized.
+ *
+ * @param body      The prepare body function (as extracted by the transform).
+ * @param planLabel A human-readable label woven into build errors (the plan id).
+ */
+declare function compilePreparedPlan(body: PreparedBody, planLabel?: string): PreparedPlanSpec;
+/** Assemble the full artifact document from compiled plans. */
+declare function buildPreparedPlanDocument(plans: Readonly<Record<string, PreparedPlanSpec>>): PreparedPlanDocument;
+
+/**
+ * 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 operation IR map. Always empty since #251 (the define*
+ *   single-op surface was removed); reads come from the contract layer.
+ * @param commands Write operation IR map. Always empty since #251; writes come
+ *   from the contract layer.
+ * @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?: Record<string, AnyOperationDefinition>, commands?: Record<string, AnyOperationDefinition>, registry?: typeof MetadataRegistry, transactions?: Record<string, TransactionDefinition>, contractInputs?: ContractInputs): BridgeBundle;
+
+export { BridgeBundle, CommandSpec, ConditionSpec, ContextOwnershipMap, type ContractBoundaryViolation, type ContractInputs, ContractMap, type ContractN1Violation, ContractSpec, ExpressionSpec, Manifest, OperationsDocument, PreparedPlanDocument, PreparedPlanSpec, QuerySpec, SpecVersion, TransactionSpec, assertBundleSerializable, assertContractBoundaries, assertContractN1Safe, assertJsonSerializable, assertSupportedCondition, buildBridgeBundle, buildManifest, buildOperations, buildPreparedPlanDocument, buildQuerySpec, buildTransactionSpec, buildTransactions, canonicalizeExpressionSpec, collectContractBoundaryViolations, collectContractN1Violations, compilePreparedPlan, operationsContainScpNodes, operationsSpecVersion };

package/dist/spec/index.js

@@ -1,41 +1,57 @@
 import {
-  MAX_TRANSACT_COMPOSE_ITEMS,
-  PREPARED_FORMAT_VERSION,
-  SPEC_VERSION,
-  assertBundleSerializable,
   assertContractBoundaries,
   assertContractN1Safe,
-  assertJsonSerializable,
-  assertNoCrossFragmentMaintainCollision,
-  assertSupportedCondition,
   buildBridgeBundle,
   buildContexts,
   buildContracts,
-  buildManifest,
   buildOperations,
   buildPreparedPlanDocument,
   buildQuerySpec,
-  buildTransactionSpec,
-  buildTransactions,
-  canonicalJson,
   collectContractBoundaryViolations,
   collectContractN1Violations,
+  compilePreparedPlan
+} from "../chunk-N4NWYNGZ.js";
+import {
+  PREPARED_FORMAT_VERSION,
+  buildManifest,
+  canonicalJson,
+  entityFingerprint,
+  planFingerprint
+} from "../chunk-LGHSZIEE.js";
+import {
+  MAX_TRANSACT_COMPOSE_ITEMS,
+  assertBundleSerializable,
+  assertJsonSerializable,
+  assertNoCrossFragmentMaintainCollision,
+  assertSupportedCondition,
+  buildTransactionSpec,
+  buildTransactions,
   compileFragment,
   compileMutationPlan,
-  compilePreparedPlan,
   compileSingleFragmentPlan,
-  entityFingerprint,
-  planFingerprint,
   resetMaintenanceGraphCache,
   resolveLifecycle,
   resolveMaintainers
-} from "../chunk-NYM7K2ST.js";
-import "../chunk-PFFPLD4B.js";
-import "../chunk-PDUVTYC5.js";
+} from "../chunk-I4LEJ4TF.js";
+import "../chunk-HNY2EJPV.js";
+import {
+  EXPR_VERSION,
+  SPEC_VERSION,
+  SPEC_VERSION_SCP,
+  SPEC_VERSION_SUPPORTED,
+  canonicalizeExpressionSpec,
+  operationsContainScpNodes,
+  operationsSpecVersion
+} from "../chunk-L4QRCHRQ.js";
+import "../chunk-L2NEDS7U.js";
+import "../chunk-XTWXMOHD.js";
 export {
+  EXPR_VERSION,
   MAX_TRANSACT_COMPOSE_ITEMS,
   PREPARED_FORMAT_VERSION,
   SPEC_VERSION,
+  SPEC_VERSION_SCP,
+  SPEC_VERSION_SUPPORTED,
   assertBundleSerializable,
   assertContractBoundaries,
   assertContractN1Safe,
@@ -52,6 +68,7 @@ export {
   buildTransactionSpec,
   buildTransactions,
   canonicalJson,
+  canonicalizeExpressionSpec,
   collectContractBoundaryViolations,
   collectContractN1Violations,
   compileFragment,
@@ -59,6 +76,8 @@ export {
   compilePreparedPlan,
   compileSingleFragmentPlan,
   entityFingerprint,
+  operationsContainScpNodes,
+  operationsSpecVersion,
   planFingerprint,
   resetMaintenanceGraphCache,
   resolveLifecycle,

package/dist/testing/index.d.ts

@@ -1,5 +1,5 @@
-import { n as Executor, D as DynamoDBOperation, o as ReadExecOptions, p as ExecutorResult, q as BatchGetExecInput, P as PutInput, W as WriteExecOptions, r as WriteResult, s as UpdateInput, t as DeleteInput, u as BatchWriteExecItem, v as BatchExecOptions, T as TransactWriteExecItem, M as ModelStatic, w as DDBModel, c as ChangeEvent } from '../maintenance-view-adapter-BATUh_I8.js';
-import '@aws-sdk/client-dynamodb';
+import { n as Executor, o as DynamoDBOperation, R as ReadExecOptions, p as ExecutorResult, B as BatchGetExecInput, q as PutInput, W as WriteExecOptions, r as WriteResult, U as UpdateInput, s as DeleteInput, t as BatchWriteExecItem, u as BatchExecOptions, T as TransactWriteExecItem, M as ModelStatic, D as DDBModel, v as ChangeEvent } from '../key-DR7_lpyk.js';
+import '../types-2PMXEn5x.js';
 
 /**
  * In-process physical store backing the GraphDDB Memory Test Adapter

package/dist/testing/index.js

@@ -1,14 +1,15 @@
 import {
   createCdcEmulator
-} from "../chunk-ZPNRLOKA.js";
+} from "../chunk-GS4C5VGO.js";
+import "../chunk-HNY2EJPV.js";
 import {
   ClientManager,
   MetadataRegistry,
   resolveModelClass
-} from "../chunk-PFFPLD4B.js";
+} from "../chunk-L2NEDS7U.js";
 import {
   TableMapping
-} from "../chunk-PDUVTYC5.js";
+} from "../chunk-XTWXMOHD.js";
 
 // src/memory/memory-store.ts
 function deepClone(value) {