graphddb 0.7.8 → 0.7.10

package/dist/types-BQLzTEqh.d.ts

@@ -0,0 +1,1207 @@
+/**
+ * Parameter placeholders for the parameterized query / command definition DSL
+ * (issue #41, Python-bridge Phase 0a).
+ *
+ * A `Param<T>` is a **branded placeholder** standing in for a value that is not
+ * known at definition time but is supplied later (at execution, e.g. from
+ * Python). It carries:
+ *
+ * - the **TypeScript value type** `T` it represents (`string`, `number`, or a
+ *   string-literal union), preserved through the IR and the inferred return
+ *   types of `defineQueries` / `defineCommands`; and
+ * - a **runtime descriptor** (`kind` + optional `literals`) that the static
+ *   planner (#42) and the code generator read to emit `operations.json`.
+ *
+ * Placeholders are created with `param.string()`, `param.number()`, and
+ * `param.literal(...)`. They are *only* legal at value positions inside a
+ * parameterized key / changes structure passed to the `define*` entry points —
+ * never to the live `Model.query` / `Model.putItem` runtime API, whose types remain
+ * uncontaminated by params.
+ */
+/** Brand tag preventing a plain object from structurally matching a {@link Param}. */
+declare const PARAM_BRAND: unique symbol;
+/** Runtime discriminant for a parameter placeholder. */
+type ParamKind = 'string' | 'number' | 'literal' | 'array';
+/**
+ * A branded parameter placeholder representing a value of TypeScript type `T`
+ * that is bound at execution time rather than definition time.
+ *
+ * The brand (`[PARAM_BRAND]: T`) keeps `Param<string>` and `Param<number>`
+ * distinct and prevents a bare value from being mistaken for a placeholder.
+ *
+ * @typeParam T - The value type this placeholder stands in for.
+ */
+interface Param<out T> {
+    /** @internal Type brand carrying the represented value type. */
+    readonly [PARAM_BRAND]: T;
+    /** Runtime discriminant: `'string'` | `'number'` | `'literal'` | `'array'`. */
+    readonly kind: ParamKind;
+    /**
+     * For `param.literal(...)`, the allowed literal values (preserved at runtime
+     * for the generator). `undefined` for `string` / `number`.
+     */
+    readonly literals?: readonly T[];
+    /**
+     * For `param.array({...})`, the descriptor of each element's fields. Lets the
+     * transaction planner (#46) type `forEach` element references and emit the
+     * `{item.<field>}` templates. `undefined` for scalar params.
+     */
+    readonly element?: Readonly<Record<string, Param<unknown>>>;
+    /**
+     * Optional human-readable description of the parameter (issue #154), supplied
+     * via `param.string({ description })` etc. Pure documentation metadata — it does
+     * NOT affect the runtime descriptor (`kind` / `literals`) the planner reads for
+     * execution. When present it is propagated to the param's {@link
+     * import('./ir.js').ParamDescriptor} and then to the serialized
+     * {@link import('../spec/types.js').ParamSpec} in `operations.json`. Absent →
+     * unchanged output (backward compatible).
+     */
+    readonly description?: string;
+}
+/** A `Param` whose represented value type is `string`. */
+type StringParam = Param<string>;
+/** A `Param` whose represented value type is `number`. */
+type NumberParam = Param<number>;
+/** A `Param` whose represented value type is the literal union `L`. */
+type LiteralParam<L extends string | number> = Param<L>;
+/** The element-field descriptor shape accepted by {@link param.array}. */
+type ArrayElementShape = Record<string, Param<unknown>>;
+/**
+ * The TypeScript element type implied by an {@link ArrayElementShape} `E`: each
+ * field carries the value type its placeholder represents.
+ */
+type ElementOf<E extends ArrayElementShape> = {
+    [K in keyof E]: E[K] extends Param<infer V> ? V : never;
+};
+/** A `Param` standing in for an **array** whose elements have shape `E`. The
+ * `kind` is narrowed to the `'array'` literal so type-level dispatch on array
+ * params works (`ParamProxy`'s array arm matches — pre-#263 the wide
+ * `ParamKind` made `p.<arrayParam>` type as a scalar ref and `ElementProxy`
+ * collapse to `never`; runtime behavior was always correct). */
+type ArrayParam<E extends ArrayElementShape> = Param<ElementOf<E>[]> & {
+    readonly kind: 'array';
+    readonly element: E;
+};
+/** Allowed scalar value types a placeholder may stand in for. */
+type ParamValue = string | number;
+/**
+ * Options accepted by the placeholder factories (issue #154). Currently carries
+ * only the optional human-readable {@link Param.description} — pure documentation
+ * metadata that does not affect the runtime descriptor. The object form is
+ * additive: `param.string()` (no options) is unchanged.
+ */
+interface ParamOptions {
+    /** Optional human-readable description, propagated to `operations.json`. */
+    readonly description?: string;
+}
+/**
+ * Placeholder factory. Each call returns a branded {@link Param} carrying both
+ * the TypeScript value type and a runtime descriptor. Each scalar factory accepts
+ * an optional {@link ParamOptions} (issue #154) carrying a `description` — pure
+ * documentation propagated to `operations.json`; the no-argument call is unchanged.
+ */
+declare const param: {
+    /** A placeholder for a `string` value. */
+    readonly string: (options?: ParamOptions) => StringParam;
+    /** A placeholder for a `number` value. */
+    readonly number: (options?: ParamOptions) => NumberParam;
+    /**
+     * A placeholder constrained to one of the given literal values. The value
+     * type of the resulting {@link Param} is the **union of the literals**, so it
+     * is preserved precisely in the IR and the inferred definition types. A final
+     * plain-object argument is read as {@link ParamOptions} (a `description`),
+     * distinguished from the `string` / `number` literal values.
+     *
+     * @example
+     * ```ts
+     * param.literal('active', 'disabled'); // Param<'active' | 'disabled'>
+     * param.literal('active', 'disabled', { description: 'Account state.' });
+     * ```
+     */
+    readonly literal: <const L extends readonly [ParamValue, ...ParamValue[]]>(...valuesAndOptions: [...L] | [...L, ParamOptions]) => LiteralParam<L[number]>;
+    /**
+     * A placeholder for an **array** parameter whose elements have the given field
+     * shape. Used by `defineTransaction`'s `tx.forEach(p.<arrayParam>, …)` to bind
+     * each element's fields to `{item.<field>}` templates.
+     *
+     * @example
+     * ```ts
+     * param.array({ userId: param.string(), role: param.string() });
+     * // Param<{ userId: string; role: string }[]>
+     * ```
+     */
+    readonly array: <const E extends ArrayElementShape>(element: E, options?: ParamOptions) => ArrayParam<E>;
+};
+/** Runtime type guard: is `value` a parameter placeholder? */
+declare function isParam(value: unknown): value is Param<unknown>;
+
+/**
+ * Serializable static operation specs and manifest (issue #42, Python-bridge
+ * Phase 0b).
+ *
+ * Everything in this module is **JSON-serializable** by construction (only
+ * strings / numbers / booleans / arrays / plain objects — no functions, classes,
+ * `Date`, `Set`, or `undefined`-valued fields are emitted). These types mirror
+ * the `graphddb_manifest.json` / `graphddb_operations.json` shapes sketched in
+ * `docs/python-bridge.md`. The generator (#43) writes them to disk; the
+ * Python runtime (#44+) interprets them.
+ *
+ * ## Templates and placeholders
+ *
+ * Key-condition / range / item / change *values* are **template strings** with
+ * two placeholder forms:
+ *
+ * - `{paramName}` — bound from the caller-supplied params at execution time.
+ * - `{result.sourceField}` — bound from a field of the **prior** operation's
+ *   result item(s), used to chain relation operations.
+ *
+ * A value with no `{...}` is a literal (e.g. a fixed sort-key discriminator
+ * `PROFILE`).
+ */
+
+/**
+ * The schema version emitted in every manifest / operations document.
+ *
+ * `1.1` (issue #208, B案): the operation IR gained the **list fan-out binding
+ * form** ({@link SourceListSpec} on a `BatchGetItem` relation op), lifting the
+ * #197 `refs` loud-reject. The op vocabulary (the physical DynamoDB API surface)
+ * is unchanged — only the dataflow (source→key) binding grammar grew. Purely
+ * additive: every `1.0` document is a valid `1.1` document, and a document that
+ * uses no `refs` relation serializes byte-identically apart from this version.
+ */
+declare const SPEC_VERSION: "1.1";
+/**
+ * The schema version stamped on an operations document that **actually
+ * contains** an SCP Expression IR node (issue #261, Phase 3 S1): a
+ * `{ kind: 'scpExpr' }` write condition or a `guard` (transaction item /
+ * contract command method). The vocabulary is purely **additive** — every
+ * `1.1` document is a valid `1.2` document — and the stamp is **conditional**:
+ * a bundle with no SCP node keeps `1.1` and serializes byte-identically to the
+ * pre-#261 output. Runtimes that do not yet EVALUATE the expression vocabulary
+ * keep `SPEC_VERSION_SUPPORTED` at `1.1`, so an expression-bearing document is
+ * loud-rejected (fail-closed) everywhere until the evaluation sub-issues
+ * (#265/#266/#267) land and bump the supported constant with the wiring.
+ */
+declare const SPEC_VERSION_SCP: "1.2";
+/**
+ * The HIGHEST spec-IR minor this **TS runtime** understands and will EXECUTE
+ * (issue #265, Phase 3 S5). The shared `validateEnvelope` fail-closed rule is
+ * "major must match, minor must be ≤ supported" (envelope.ts): a bundle stamped
+ * at or below this version loads; a newer minor (or a bad major) is loud-rejected.
+ *
+ * S1 kept this at `1.1` so an expression-bearing `1.2` bundle was rejected
+ * everywhere (fail-closed) until evaluation landed. S5 wires the TS guard
+ * evaluator to `behavior-contracts` and moves it to `1.2`, so a guard-bearing
+ * `1.2` bundle is now ACCEPTED and EVALUATED on TS. A `1.2` bundle carrying an
+ * unknown `exprVersion` / operator still fail-closes (the expr evaluator rejects
+ * it). The py/rust/go runtimes bump in S6, PHP in S7 — the whole release column
+ * moves to `1.2` together.
+ */
+declare const SPEC_VERSION_SUPPORTED: "1.2";
+/** A spec version an operations document may carry (see {@link SPEC_VERSION_SCP}). */
+type SpecVersion = typeof SPEC_VERSION | typeof SPEC_VERSION_SCP;
+/** Field type as carried in the manifest (derived from the DynamoDB type). */
+type ManifestFieldType = 'string' | 'number' | 'boolean' | 'binary' | 'stringSet' | 'numberSet' | 'list' | 'map';
+interface ManifestField {
+    readonly type: ManifestFieldType;
+    /**
+     * Semantic format for `string` fields that carry a serialized temporal value.
+     * `datetime` → ISO 8601 instant, `date` → `YYYY-MM-DD`. Absent for plain
+     * fields. The Python runtime uses this to restore `datetime` on hydration,
+     * mirroring the TS hydrator's `format`-driven `Date` reconstruction.
+     */
+    readonly format?: 'datetime' | 'date';
+    /**
+     * Optional human-readable description of the field (issue #154), from a field
+     * decorator option (`@string({ description })`). Pure documentation — absent
+     * unless declared, so a field with no description serializes byte-identically
+     * to the pre-#154 manifest. Surfaces as a field comment in the generated Python.
+     */
+    readonly description?: string;
+}
+/** A key (PK or GSI) template descriptor in the manifest. */
+interface ManifestKey {
+    /** Input field names the key is composed from (in declaration order). */
+    readonly inputFields: readonly string[];
+    /** Template for the partition-key value, e.g. `EMAIL#{email}`. */
+    readonly pkTemplate: string;
+    /** Template for the sort-key value, or `null` when the key has no sort key. */
+    readonly skTemplate: string | null;
+}
+interface ManifestGsi extends ManifestKey {
+    readonly indexName: string;
+    readonly unique: boolean;
+    /**
+     * Optional human-readable description of the index (issue #166, follow-up of #154),
+     * from `gsi(name, key, { description })`. Pure documentation — absent unless declared,
+     * so a GSI with no description serializes byte-identically to the pre-#166 manifest.
+     * The Python codegen surfaces it as the docstring of a generated query method that
+     * reads through this index.
+     */
+    readonly description?: string;
+}
+interface ManifestRelation {
+    readonly type: 'hasMany' | 'hasOne' | 'belongsTo' | 'refs';
+    /** Target entity (model class) name. */
+    readonly target: string;
+    /** target field → source field (on this entity). */
+    readonly keyBinding: Readonly<Record<string, string>>;
+    /**
+     * List-valued source descriptor for a `refs` relation (issue #197). Present IFF
+     * `type === 'refs'`: `from` is the parent LIST attribute holding the inline
+     * reference elements (e.g. `'tagRefs'`), `key` the field read off each element
+     * (e.g. `'tagId'`). Absent for every scalar-keyed relation (byte-identical to
+     * the pre-#197 manifest). Carried so a manifest consumer can reconstruct where a
+     * `refs` relation's BatchGet keys come from.
+     */
+    readonly refs?: Readonly<{
+        from: string;
+        key: string;
+    }>;
+    /**
+     * Optional human-readable description of the relation (issue #166, follow-up of
+     * #154), from `@hasMany/@belongsTo/@hasOne(..., { description })`. Pure documentation
+     * — absent unless declared, so a relation with no description serializes
+     * byte-identically to the pre-#166 manifest. The Python codegen surfaces it as a
+     * trailing `# …` comment on the relation's field in the generated result type.
+     */
+    readonly description?: string;
+}
+interface ManifestEntity {
+    /** Declared (logical) table name. */
+    readonly table: string;
+    /** Physical table name (after `TableMapping` resolution). */
+    readonly physicalName: string;
+    /** PK prefix, e.g. `USER#`. */
+    readonly prefix: string;
+    readonly fields: Readonly<Record<string, ManifestField>>;
+    /** Primary key, or `null` when the entity has none. */
+    readonly key: ManifestKey | null;
+    readonly gsis: readonly ManifestGsi[];
+    readonly relations: Readonly<Record<string, ManifestRelation>>;
+    /**
+     * Optional human-readable description of the entity (issue #154), from
+     * `@model({ description })`. Pure documentation — absent unless declared, so an
+     * entity with no description serializes byte-identically to the pre-#154
+     * manifest. Surfaces as the generated Python class docstring.
+     */
+    readonly description?: string;
+    /**
+     * The physical attribute name of the model's DynamoDB **Time-To-Live** field,
+     * when one is declared via `@ttl` (issue #172, Epic #167 — CFn generator C4).
+     * Unlike the maintenance/stream signals (a maintenance-IR concern kept OFF the
+     * manifest), TTL is a **physical schema** fact, and the CloudFormation emitter
+     * consumes the manifest — so the TTL attribute name flows here and the emitter
+     * renders `TimeToLiveSpecification { AttributeName: <this>, Enabled: true }`. The
+     * attribute is deliberately NOT added to the table's key `AttributeDefinitions`
+     * (that list holds ONLY key/index attributes; `TimeToLiveSpecification` legitimately
+     * names a non-key attribute). **Absent** when the model declares no `@ttl`, so a
+     * TTL-free model serializes byte-identically to the pre-#172 manifest (backward
+     * compatible). DynamoDB permits exactly one TTL attribute per physical table; the
+     * single-per-table rule is enforced at manifest build.
+     */
+    readonly ttlAttribute?: string;
+}
+interface ManifestTable {
+    readonly physicalName: string;
+}
+interface Manifest {
+    /**
+     * Always the base {@link SPEC_VERSION}: the manifest carries entity/schema
+     * metadata only — the SCP Expression IR vocabulary (issue #261) lives in the
+     * operations document, so the conditional `1.2` stamp never applies here and
+     * every manifest stays byte-identical.
+     */
+    readonly version: typeof SPEC_VERSION;
+    readonly tables: Readonly<Record<string, ManifestTable>>;
+    readonly entities: Readonly<Record<string, ManifestEntity>>;
+}
+interface ParamSpec {
+    readonly type: ParamKind;
+    readonly required: boolean;
+    /** Allowed literal values for `literal` params; omitted otherwise. */
+    readonly literals?: readonly (string | number)[];
+    /**
+     * For an `array` param (transaction `forEach` source), the per-element field
+     * descriptors (field name → element param spec). Omitted for scalar params.
+     */
+    readonly element?: Readonly<Record<string, ParamSpec>>;
+    /**
+     * Optional human-readable description of the parameter (issue #154), from a
+     * `param.*({ description })` placeholder. Pure documentation — absent unless
+     * declared, so a param with no description serializes byte-identically to the
+     * pre-#154 spec. The Python runtime never reads it for execution.
+     */
+    readonly description?: string;
+}
+/** A `begins_with` range condition on a sort key (templated value). */
+interface RangeConditionSpec {
+    readonly operator: 'begins_with';
+    readonly key: string;
+    /** Template value, e.g. `GROUP#` or `GROUP#{result.groupId}`. */
+    readonly value: string;
+}
+/** Server-side declarative filter, carried verbatim for the runtime to compile. */
+interface FilterSpec {
+    /** The declarative {@link FilterInput} tree (JSON-safe). */
+    readonly declarative: unknown;
+}
+type ReadOperationType = 'Query' | 'GetItem' | 'BatchGetItem';
+/**
+ * A single static read operation. Relation chains are expressed as multiple
+ * operations whose `resultPath` / templated key conditions wire them together.
+ */
+interface OperationSpec {
+    readonly type: ReadOperationType;
+    readonly tableName: string;
+    readonly indexName?: string;
+    /**
+     * Key condition: attribute name → template value. For a `BatchGetItem` this is
+     * the per-key shape (one key per resolved source item at runtime).
+     */
+    readonly keyCondition: Readonly<Record<string, string>>;
+    readonly rangeCondition?: RangeConditionSpec;
+    /** Projected fields (entity field names). */
+    readonly projection: readonly string[];
+    readonly limit?: number;
+    readonly filter?: FilterSpec;
+    /**
+     * Where the result of this operation is placed in the assembled result.
+     * `$` is the root; `$.groups.items` a relation connection's items, etc.
+     */
+    readonly resultPath: string;
+    /**
+     * For relation operations: the source field on the prior result whose value(s)
+     * drive this operation's `{result.*}` placeholders. Absent on the root op.
+     */
+    readonly sourceField?: string;
+    /**
+     * The **list fan-out binding form** (issue #208, B案 — the shared-IR
+     * generalization that lifted the #197 `refs` loud-reject). Present only on a
+     * `BatchGetItem` relation operation that resolves a `refs` relation: instead of
+     * reading ONE scalar `parent[sourceField]`, the runtime reads the parent **list
+     * attribute** {@link SourceListSpec.from} and binds `{result.<sourceField>}`
+     * once per element — `element[key]` for an object element, the element itself
+     * for a bare scalar — skipping null/undefined refs. All element keys across all
+     * parents fan into ONE deduped `BatchGetItem` (the existing chunk/retry
+     * machinery), and the operation's `resultPath` (`…<prop>.items`) receives a
+     * connection `{ items, cursor: null }` whose items are the resolved child
+     * bodies in **first-seen element order**, deduped, with missing bodies dropped
+     * — byte-matching the TS in-process `fetchRefsList` semantics. Absent on every
+     * scalar-bound relation op (a pre-#208 document is byte-identical).
+     */
+    readonly sourceList?: SourceListSpec;
+}
+/**
+ * The list-valued source descriptor of a fan-out `BatchGetItem` operation (issue
+ * #208 B案; the operation-IR mirror of the manifest's `ManifestRelation.refs`).
+ */
+interface SourceListSpec {
+    /** The parent LIST attribute holding the inline reference elements (e.g. `tagRefs`). */
+    readonly from: string;
+    /**
+     * The field read off each element (e.g. `tagId`). Always equals the operation's
+     * `sourceField` (the `{result.<sourceField>}` token name); carried explicitly so
+     * the op is self-describing.
+     */
+    readonly key: string;
+    /**
+     * `true` when the parent list attribute was NOT selected by the query and was
+     * projected onto the parent operation **solely** to drive this fan-out. The
+     * runtime must then delete `from` from every parent node after ALL relation
+     * operations are applied — mirroring the TS hydrator, which projects implicit
+     * relation-source fields but strips them from the assembled result. Absent when
+     * the query's select projects the attribute itself (it stays in the result).
+     */
+    readonly implicit?: boolean;
+}
+/**
+ * The **execution plan** for a multi-operation read (issue #70a). It is the
+ * Single Source of Truth for *how* a query's {@link OperationSpec}[] is staged:
+ * which operations are independent (may run concurrently) and which must wait for
+ * a prior operation's result. Every runtime that honors it produces identical
+ * effects with identical concurrency discipline — the staging is **serialized,
+ * not re-derived** (cf. the contract decided-facts discipline).
+ *
+ * - `groups` is an ordered list of **stages**; each stage is a list of indices
+ *   into the query's `operations[]`. Operations **within** a stage are mutually
+ *   independent and may be issued concurrently; stages run **in order** because a
+ *   later stage reads a `{result.*}` value produced by an earlier one. Stage 0 is
+ *   always `[0]` (the root). Every operation index appears in exactly one stage,
+ *   and the stages are a topological layering of the result-dependency graph.
+ * - `concurrency` is the declared in-flight bound a runtime applies **within**
+ *   each stage (the shared {@link RELATION_TRAVERSAL_CONCURRENCY} = 16): at most
+ *   this many operations of a stage are issued at once.
+ *
+ * ## Derivation (see `buildReadOperations` / `deriveExecutionPlan`)
+ *
+ * The planner emits `operations[]` in a deterministic pre-order: the root at
+ * index 0, then each relation child immediately followed by its own descendants.
+ * A child's key templates reference `{result.<sourceField>}` of the **operation
+ * whose `resultPath` is the child's parent path** — that producer is the child's
+ * sole dependency. The stage of an operation is therefore `1 + stage(parent)`:
+ * the root is stage 0; sibling relations that share a parent path land in the
+ * **same** stage (no inter-`{result.*}` dependency between siblings, so they are
+ * independent and concurrency-eligible); a grandchild that reads its parent's
+ * `{result.*}` lands one stage later. This mirrors exactly the level-by-level
+ * fan-out the TS relation runtime performs at runtime (`resolveRelations` issues
+ * sibling relations together under the same bound) — #70a only *records* it.
+ *
+ * Absent on a single-operation spec and on specs produced before #70a; a consumer
+ * without a plan falls back to one-operation-per-stage **sequential** execution
+ * (the pre-#70 behavior), so an absent plan never changes results.
+ */
+interface ExecutionPlanSpec {
+    /** Ordered stages; each stage is indices into `operations[]` (stage 0 = `[0]`). */
+    readonly groups: readonly (readonly number[])[];
+    /** The declared in-flight bound applied within each stage (16). */
+    readonly concurrency: number;
+}
+/** A query (read) definition's full execution spec. */
+interface QuerySpec {
+    readonly params: Readonly<Record<string, ParamSpec>>;
+    readonly operations: readonly OperationSpec[];
+    /**
+     * Result cardinality of the **root** (`$`) operation, derived from the
+     * definition kind: `'one'` for `defineQuery` (a single entity object, with any
+     * relations attached directly), `'many'` for `defineList` (a `{ items, cursor }`
+     * connection). The relation runtime (#45) uses this to shape the root result:
+     * a `'one'` Query root takes the first matched item rather than returning a
+     * connection. Absent in specs produced before #45; consumers should treat an
+     * absent value as `'many'` for a `Query`/`BatchGetItem` root and `'one'` for a
+     * `GetItem` root (the pre-#45 behavior).
+     */
+    readonly cardinality?: 'one' | 'many';
+    /**
+     * The staged execution plan (issue #70a): which {@link operations} are
+     * independent (concurrency-eligible) vs. result-dependent. Present only when the
+     * query has more than one operation (a relation chain); a single-operation read
+     * needs no plan. See {@link ExecutionPlanSpec} for the derivation and the
+     * backward-compatible (plan-absent → sequential) fallback.
+     */
+    readonly executionPlan?: ExecutionPlanSpec;
+    /**
+     * Optional human-readable description of the query (issue #154), from
+     * `defineQuery(..., { description })`. Pure documentation — absent unless
+     * declared, so a query with no description serializes byte-identically to the
+     * pre-#154 spec. Surfaces as the generated Python repository-method docstring.
+     */
+    readonly description?: string;
+}
+/**
+ * The Expression IR vocabulary version (behavior-contracts `expression-ir.md`
+ * §9). A runtime handed an unknown `exprVersion` MUST fail closed.
+ */
+declare const EXPR_VERSION: 1;
+/**
+ * The closed operator vocabulary of Expression IR v1 (expression-ir.md §3).
+ * An operator node is a **single-key** object — key = operator name, value =
+ * the argument array. Anything outside this set is invalid IR (fail-closed).
+ */
+type ExpressionOperator = 'add' | 'sub' | 'mul' | 'div' | 'mod' | 'neg' | 'concat' | 'eq' | 'ne' | 'lt' | 'le' | 'gt' | 'ge' | 'and' | 'or' | 'not' | 'coalesce' | 'cond' | 'len';
+/**
+ * A scalar literal carried as-is (expression-ir.md §2.1). `number` follows the
+ * §2.3 classification rule: a fractional value is a float; an integer value is
+ * an int and MUST be within the safe-integer range (beyond it the literal is
+ * carried as {@link ExpressionIntNode}). NaN / ±Infinity / undefined cannot
+ * exist in the IR.
+ */
+type ExpressionScalar = string | number | boolean | null;
+/** Strict member access (`a.b.c`); a null intermediate is a Failure (§2.2). */
+interface ExpressionRefNode {
+    readonly ref: readonly string[];
+}
+/** Null-propagating member access (`a?.b`); a null intermediate → null (§2.2). */
+interface ExpressionRefOptNode {
+    readonly refOpt: readonly string[];
+}
+/** Object construction (`{ x: <expr> }`, §2.3). Keys sort canonically. */
+interface ExpressionObjNode {
+    readonly obj: Readonly<Record<string, ExpressionNode>>;
+}
+/** Array construction (`[a, b]`, §2.3). */
+interface ExpressionArrNode {
+    readonly arr: readonly ExpressionNode[];
+}
+/**
+ * An int literal beyond the safe-integer range (±2^53−1), carried as a string
+ * because a raw JSON number would lose precision in TS (§2.3). Must fit i64.
+ */
+interface ExpressionIntNode {
+    readonly int: string;
+}
+/**
+ * An **integer-valued** float literal (TS surface `1.0`), wrapped because JSON
+ * does not preserve the decimal point (§2.3). A fractional float (`1.5`) is a
+ * plain JSON number.
+ */
+interface ExpressionFloatNode {
+    readonly float: number;
+}
+/**
+ * An operator node: a single-key object mapping one {@link ExpressionOperator}
+ * to its argument array (§2.1). The mapped-union form makes each member carry
+ * **exactly** its one operator key.
+ */
+type ExpressionOpNode = {
+    [K in ExpressionOperator]: {
+        readonly [P in K]: readonly ExpressionNode[];
+    };
+}[ExpressionOperator];
+/**
+ * One Expression IR node (expression-ir.md §2): a scalar literal, a reference,
+ * a construction form, a wrapped int/float literal, or an operator node.
+ */
+type ExpressionNode = ExpressionScalar | ExpressionRefNode | ExpressionRefOptNode | ExpressionObjNode | ExpressionArrNode | ExpressionIntNode | ExpressionFloatNode | ExpressionOpNode;
+/**
+ * A serialized SCP expression (issue #261): the versioned envelope around one
+ * Expression IR node. This is the payload of a `{ kind: 'scpExpr' }` write
+ * condition and of every `guard` slot. The embedded `expr` is stored in
+ * **canonical form** (§2.3/§2.4: key-sorted at every level — code-point order —
+ * with `{int:"…"}` / `{float:n}` literal wrapping), produced by
+ * `canonicalizeExpressionSpec` in `src/spec/expression.ts`, so the document
+ * serializes deterministically through the ordinary JSON emitters.
+ */
+interface ExpressionSpec {
+    readonly exprVersion: typeof EXPR_VERSION;
+    readonly expr: ExpressionNode;
+}
+type WriteOperationType = 'PutItem' | 'UpdateItem' | 'DeleteItem';
+/**
+ * A condition expression on a write, as a JSON-serializable spec (issues #46,
+ * #81). The supported subset:
+ *
+ * - `{ kind: 'notExists' }` → `attribute_not_exists(PK)` (legacy whole-row guard).
+ * - `{ kind: 'attributeExists'; field }` → `attribute_exists(<field>)` — the named
+ *   attribute (any field, incl. PK/SK) must be present. The foundation for
+ *   referential-integrity derivation.
+ * - `{ kind: 'attributeNotExists'; field }` → `attribute_not_exists(<field>)` — the
+ *   named attribute must be absent (field-level uniqueness / first-write guard).
+ * - `{ kind: 'equals'; fields }` → `#f = :v AND …` field equality (each value a
+ *   `{param}` / literal template).
+ * - `{ kind: 'expr'; declarative }` → the full declarative operator tree (issue
+ *   #114-A): comparison (`gt`/`ge`/`lt`/`le`/`ne`), `between`, `in`,
+ *   `begins_with`/`contains`/`notContains`, `attributeType`, and the logical
+ *   `and`/`or`/`not` groups, mirroring the read-side {@link FilterSpec}. The tree
+ *   is JSON-safe: each leaf value is either a native literal (string / number /
+ *   boolean) or a {@link ConditionParamLeaf} (`{ $param }`) marking a caller
+ *   param bound at execution time. The runtime resolves the param leaves against
+ *   the caller params, then compiles the tree to a DynamoDB `ConditionExpression`
+ *   with the SAME mechanics the filter compiler uses (so TS and Python emit an
+ *   identical expression / semantics).
+ */
+type ConditionSpec = {
+    readonly kind: 'notExists';
+} | {
+    readonly kind: 'attributeExists';
+    readonly field: string;
+} | {
+    readonly kind: 'attributeNotExists';
+    readonly field: string;
+} | {
+    readonly kind: 'equals';
+    readonly fields: Readonly<Record<string, string>>;
+} | {
+    readonly kind: 'expr';
+    readonly declarative: unknown;
+} | {
+    /**
+     * A raw DynamoDB condition produced by the `cond` escape hatch (issue
+     * #114-B), for write conditions that the declarative operator subset
+     * cannot express. It is **pre-compiled and deterministic**: the
+     * `expression` is a finished DynamoDB `ConditionExpression` whose name
+     * placeholders are stable `#cr_<field>` aliases (reused per distinct
+     * column) and whose value placeholders are sequential `:cr0`, `:cr1`, …
+     * (assigned in template order), so the serialized golden is stable. The
+     * names map binds each `#cr_<field>` alias to its entity field; the values
+     * map binds each `:crN` alias to either a native literal (an embedded
+     * `cond` value — in-process the concrete value) or a {@link ConditionParamLeaf}
+     * (`{ $param }`) marker bound from a caller param at execution time (the
+     * public-contract slot). The runtime substitutes the param leaves, then
+     * attaches `expression` / `names` / serialized `values` to the write —
+     * TS and Python build the identical DynamoDB expression.
+     */
+    readonly kind: 'raw';
+    readonly expression: string;
+    readonly names: Readonly<Record<string, string>>;
+    readonly values: Readonly<Record<string, unknown>>;
+} | {
+    /**
+     * An SCP Expression IR write condition (issue #261, Phase 3 S1): the
+     * condition is a behavior-contracts `expression-ir.md` §2 expression,
+     * carried as a versioned {@link ExpressionSpec} in canonical form. A
+     * document containing this variant is stamped spec version
+     * {@link SPEC_VERSION_SCP} (`1.2`, conditional stamping), so a runtime
+     * that does not yet evaluate the expression vocabulary loud-rejects the
+     * whole document (fail-closed) instead of silently dropping the
+     * condition. Evaluation wiring is the Phase 3 S5/S6/S7 sub-issues.
+     */
+    readonly kind: 'scpExpr';
+    readonly expression: ExpressionSpec;
+};
+interface CommandSpec {
+    readonly type: WriteOperationType;
+    readonly tableName: string;
+    readonly entity: string;
+    readonly params: Readonly<Record<string, ParamSpec>>;
+    /**
+     * Key condition for `UpdateItem` / `DeleteItem` (attribute name → template).
+     * Absent for `PutItem` (the whole item is built from `item`).
+     */
+    readonly keyCondition?: Readonly<Record<string, string>>;
+    /** The full item template for `PutItem` (field name → template / literal). */
+    readonly item?: Readonly<Record<string, string>>;
+    /** Field-level changes for `UpdateItem` (field name → template / literal). */
+    readonly changes?: Readonly<Record<string, string>>;
+    /** Optional write condition (subset). */
+    readonly condition?: ConditionSpec;
+    /**
+     * Optional human-readable description of the command (issue #154), from
+     * `definePut`/`defineUpdate`/`defineDelete(..., { description })`. Pure
+     * documentation — absent unless declared, so a command with no description
+     * serializes byte-identically to the pre-#154 spec. Surfaces as the generated
+     * Python repository-method docstring.
+     */
+    readonly description?: string;
+}
+/**
+ * A declarative `when` guard on a transaction item (issue #46). Compares a
+ * templated left-hand value against a templated right-hand value; the item is
+ * skipped when the comparison does not hold. Both values are template strings
+ * (`{param}` / `{item.<field>}` / literal), resolved by the runtime before the
+ * comparison. The runtime compares the resolved **string** values.
+ */
+interface WhenSpec {
+    readonly op: 'eq' | 'ne';
+    /** Templated left-hand value (typically an `{item.<field>}` or `{param}`). */
+    readonly left: string;
+    /** Templated right-hand value (literal or another reference). */
+    readonly right: string;
+}
+/**
+ * The kind of a transaction item. The three write kinds (`Put` / `Update` /
+ * `Delete`) mutate an item; `ConditionCheck` (issue #81) is a **read-only
+ * assertion** on another item — it asserts a {@link ConditionSpec} holds for the
+ * keyed row without modifying it, and its failure cancels the **whole**
+ * `TransactWriteItems` atomically. It is the foundation for referential-integrity
+ * derivation (proposal: `requires <Entity> exists` → a `ConditionCheck` with
+ * `attribute_exists`).
+ */
+type TransactionItemType = 'Put' | 'Update' | 'Delete' | 'ConditionCheck';
+/**
+ * A value leaf of a transaction `item` / `changes` / `add` map (issue #245).
+ *
+ * - a **string** carries a template: a `{param}` / `{item.field}` placeholder, a
+ *   composite (`PREFIX#{param}`), or a plain string literal — resolved by the
+ *   runtimes' template machinery (a whole-placeholder string keeps the bound
+ *   param's *type*, a composite / plain string resolves to a string);
+ * - a **number** / **boolean** carries a *typed literal* verbatim, so a numeric
+ *   literal in a `put` item / `update` changes (`version: 0`) survives to DynamoDB
+ *   as an `N` / `BOOL` instead of being stringified to an `S` (the pre-#245 bug).
+ *
+ * A `Date` literal is serialized to its ISO-8601 **string** at build time (a
+ * `@datetime` / `@date` field is stored as `S`), so it stays a string leaf.
+ */
+type TransactionValueLeaf = string | number | boolean;
+/**
+ * A single templated item in a transaction. When `forEach` is present, the item
+ * is expanded **once per element** of the named array param, with each element's
+ * fields bound to the item's `{item.<field>}` placeholders.
+ *
+ * Field presence by `type`:
+ *
+ * | type           | item | keyCondition | changes | add | condition                |
+ * |----------------|------|--------------|---------|-----|--------------------------|
+ * | `Put`          | ✓    | —            | —       | —   | optional                 |
+ * | `Update`       | —    | ✓            | ✓ / —   | ✓ / — | optional               |
+ * | `Delete`       | —    | ✓            | —       | —   | optional                 |
+ * | `ConditionCheck` | —  | ✓            | —       | —   | **required** (the assert) |
+ *
+ * An `Update` carries `changes` (a `SET` of named fields) and/or `add` (an atomic
+ * `ADD` of named numeric fields, issue #85) — at least one of the two. The two are
+ * distinct DynamoDB update actions: `SET #f = :v` **overwrites**, while
+ * `ADD #f :delta` **atomically increments** without a read (concurrency-safe), so
+ * a derived counter (`User.postCount += 1`) MUST be an `add`, never a `changes`
+ * `SET` (which would clobber a concurrent increment).
+ */
+interface TransactionItemSpec {
+    readonly type: TransactionItemType;
+    readonly tableName: string;
+    readonly entity: string;
+    /**
+     * Put: the full item template (field → template / typed literal). A string
+     * value is a template ({@link TransactionValueLeaf}); a `number` / `boolean` is
+     * a typed literal carried verbatim (issue #245).
+     */
+    readonly item?: Readonly<Record<string, TransactionValueLeaf>>;
+    /** Update / Delete / ConditionCheck: the key template (attribute → template). */
+    readonly keyCondition?: Readonly<Record<string, string>>;
+    /**
+     * Update: field-level `SET` change templates (overwrite). A string value is a
+     * template; a `number` / `boolean` is a typed literal carried verbatim (#245).
+     */
+    readonly changes?: Readonly<Record<string, TransactionValueLeaf>>;
+    /**
+     * Update: field-level atomic `ADD` deltas (issue #85, derived counters). Each
+     * value is a numeric template (`{param}` / a literal number string) or a typed
+     * numeric literal (issue #245); the runtime applies `ADD #field :delta`, an
+     * atomic increment that needs no prior read and is safe under concurrency. A
+     * negative delta decrements (e.g. `-1` on a remove).
+     */
+    readonly add?: Readonly<Record<string, TransactionValueLeaf>>;
+    /**
+     * The write / assertion condition (subset). Optional on `Put` / `Update` /
+     * `Delete`; **required** on a `ConditionCheck` (the assertion it makes).
+     */
+    readonly condition?: ConditionSpec;
+    /** Optional declarative guard; the item is skipped when it does not hold. */
+    readonly when?: WhenSpec;
+    /**
+     * Optional SCP expression guard (issue #261, Phase 3 S1): a boolean
+     * behavior-contracts Expression IR expression, carried beside the legacy
+     * {@link when} comparison. The item is skipped when the expression does not
+     * hold. A document carrying a `guard` is stamped {@link SPEC_VERSION_SCP}
+     * (`1.2`), so a runtime that does not yet evaluate the expression vocabulary
+     * loud-rejects the whole document rather than silently skipping the guard
+     * (fail-closed; evaluation wiring is Phase 3 S5/S6/S7). `when` removal is
+     * the 0.8.0 reorg (#251/#252).
+     */
+    readonly guard?: ExpressionSpec;
+    /** When present, expand this item once per element of the named array param. */
+    readonly forEach?: {
+        readonly source: string;
+    };
+    /**
+     * Marks a **raw marker-row** write (issue #86 uniqueness guard): the row is NOT a
+     * modeled entity, so its primary key is carried **literally** rather than derived
+     * from manifest metadata. When `true`:
+     *
+     * - a `Put` writes its `item` record **verbatim** as the stored item — the `item`
+     *   already carries the synthetic `PK` / `SK` templates (`UNIQUE#…`), so the
+     *   runtimes do NOT prepend a model prefix or compute GSI attributes;
+     * - a `Delete` uses its `keyCondition` (the `PK` / `SK` templates) as the row Key
+     *   verbatim.
+     *
+     * The companion {@link entity} is the {@link MARKER_ROW_ENTITY} sentinel (there is
+     * no manifest entity to resolve). Absent / `false` on every modeled write (a base
+     * entity / edge / counter / ConditionCheck item), so those paths are unchanged.
+     */
+    readonly literalKey?: boolean;
+    /**
+     * A **relation-side maintenance write** (Epic #118, issue #129 — the JSON-SSoT /
+     * Python mirror of the TS in-process `renderMaintainWriteItem`). Present ONLY on an
+     * `Update` item that materializes a maintained access path: a projected
+     * {@link DerivedMaintainWrite} of a just-written source row into a SEPARATE owner
+     * (destination) row, in the SAME atomic transaction as the source write.
+     *
+     * The item's {@link keyCondition} carries the owner row's key templates (bound from
+     * the source payload — `{sourceInputField}`), so the same key derivation / collapse
+     * signature the other `Update` items use applies unchanged. This `maintain` payload
+     * carries the projection transform IR (`identity` / `preview`) the runtimes apply
+     * IDENTICALLY when rendering the `SET … = :v` (snapshot) / `list_append(…)`
+     * (collection) `UpdateExpression`, so the maintained row is byte-consistent across
+     * TS and Python. The `changes` / `add` fields are NOT used when this is present.
+     */
+    readonly maintain?: MaintainItemSpec;
+}
+/**
+ * The transform op applied to one projected maintenance attribute (Epic #118).
+ * Mirrors `ProjectionTransformOp` from `src/define/entity-writes.ts`: `identity`
+ * copies the source value through unchanged; `preview` keeps the first `n`
+ * characters of (the string form of) the source value. The runtimes apply this
+ * IDENTICALLY so the maintained row is byte-consistent.
+ */
+type MaintainProjectionOp = 'identity' | 'preview';
+/**
+ * One projected maintenance attribute: the source value is read from the mutation
+ * input field {@link inputField} (payload 同梱 — the just-written source row image),
+ * then run through {@link op} with {@link args} (e.g. `preview`'s length bound).
+ */
+interface MaintainProjectionEntry {
+    /** The transform op applied to the source value (`identity` / `preview`). */
+    readonly op: MaintainProjectionOp;
+    /** The op's positional arguments (`[n]` for `preview`; empty for `identity`). */
+    readonly args: readonly unknown[];
+    /** The mutation-input field the source value is read from (`{inputField}`). */
+    readonly inputField: string;
+}
+/**
+ * The bounded-collection options a `collection` maintenance write carries. Phase 1
+ * is **append-only**: `maxItems` / `orderBy` are recorded for the future async trim
+ * (#130) but NOT applied synchronously — a single `UpdateExpression` cannot
+ * read-modify-write a bounded/ordered list.
+ */
+interface MaintainCollectionSpec {
+    /** The target attribute that holds the maintained collection. */
+    readonly field: string;
+    /** Cap on the collection size (recorded for #130; not trimmed in Phase 1). */
+    readonly maxItems?: number;
+    /** The mutation-input field the items are ordered by (recorded for #130). */
+    readonly orderBy?: string;
+    /** The direction `orderBy` sorts by, from the relation's `read.order` (recorded for #130). */
+    readonly orderDir?: 'ASC' | 'DESC';
+}
+/**
+ * The maintenance payload an `Update` {@link TransactionItemSpec} carries when it
+ * materializes a maintained access path (Epic #118 / #129). A `snapshot` mirrors
+ * the projection onto the owner row via `SET`; a `collection` appends the projection
+ * as an item into the bounded list named by {@link collection} via `list_append`.
+ */
+interface MaintainItemSpec {
+    /**
+     * Whether the write mirrors a single row (`snapshot`), appends a collection item
+     * (`collection`), or applies a scalar `ADD` counter (`counter`, Epic #118 / #141).
+     */
+    readonly kind: 'snapshot' | 'collection' | 'counter';
+    /** The relation property / `@aggregate` field that declared this maintenance (documentary). */
+    readonly relationProperty: string;
+    /** The trigger (`<sourceLogicalName>.<event>`) that fired this maintenance. */
+    readonly trigger: string;
+    /** target attribute → its projection transform (source field + op + args). Empty for `counter`. */
+    readonly projection: Readonly<Record<string, MaintainProjectionEntry>>;
+    /** The bounded-collection options; present only for `kind: 'collection'`. */
+    readonly collection?: MaintainCollectionSpec;
+    /**
+     * The scalar counter `ADD`; present only for `kind: 'counter'` (#141). The runtimes
+     * render `ADD #attr :delta` — an atomic, concurrency-safe increment that MERGES with
+     * a same-row counter ADD (#92), the maintenance-pipeline analogue of the
+     * self-lifecycle derived counter's `add` slot. `delta` is a numeric template string
+     * (the compile-time constant `+1` created / `-1` removed).
+     */
+    readonly counter?: MaintainCounterSpec;
+}
+/**
+ * The scalar counter a `counter` maintenance write applies (Epic #118 / #141): an
+ * atomic `ADD #attribute :delta`. `delta` is a literal numeric template string (the
+ * compile-time constant the trigger fixed — `"1"` created / `"-1"` removed); the
+ * runtimes serialize it as a number. Only `count()` is realized synchronously
+ * (`max(field)` is rejected for the synchronous path — #130 / Phase 2).
+ */
+interface MaintainCounterSpec {
+    /** The target attribute the counter increments (e.g. `postCount`). */
+    readonly attribute: string;
+    /** The signed `ADD` delta as a numeric template string (`"1"` / `"-1"`). */
+    readonly delta: string;
+}
+/** A declarative transaction definition's full execution spec. */
+interface TransactionSpec {
+    readonly params: Readonly<Record<string, ParamSpec>>;
+    readonly items: readonly TransactionItemSpec[];
+    /**
+     * A static upper bound on the expanded item count when computable (no `forEach`
+     * present → the exact count; with `forEach` it is left absent because the
+     * element count is only known at execution — the runtime then enforces the
+     * DynamoDB ≤25 limit after expansion).
+     */
+    readonly maxItems?: number;
+}
+/**
+ * Whether a contract is a public **read** (`'query'`) or **write** (`'command'`)
+ * interface. Mirrors {@link QueryModelContract} / {@link CommandModelContract}'s
+ * `kind` discriminant from the Contract IR (#58).
+ */
+type ContractKind = 'query' | 'command';
+/**
+ * The resolution kind of a contract query method, **derived** by the planner from
+ * the internal op (never hand-written; see proposal "N+1 Safety"):
+ *
+ * - `'point'` — target keys are known (unique-key `query` / `GetItem`); a key
+ *   array coalesces to one `BatchGetItem`.
+ * - `'range'` — target key set is unknown (partition `list` / `Query`); one
+ *   request per partition key, so it is only ever safe for a single key.
+ */
+type ContractResolution = 'point' | 'range';
+/**
+ * What input arity a contract method accepts, **derived** from its resolution:
+ *
+ * - `'either'` — a single key **or** an array (a `point` read / a known-key
+ *   write; the array form is one `BatchGetItem` / batched write).
+ * - `'single'` — a single key only (a `range` read; an array would be an N+1
+ *   fan-out and is rejected by construction).
+ * - `'array'` — an array only (reserved; not produced by the current resolvers).
+ */
+type ContractInputArity = 'single' | 'array' | 'either';
+/**
+ * The per-key result cardinality of a contract query method, **derived** from the
+ * internal op kind (proposal "Cardinality matrix"):
+ *
+ * - `'one'` — at most one item per key (a `point` read).
+ * - `'many'` — a connection (`{ items, cursor }`) per key (a `range` read).
+ *
+ * This is the per-key shape; the input arity (single vs. array) then decides
+ * whether the overall result is bare or keyed.
+ */
+type ContractCardinality = 'one' | 'many';
+/**
+ * The category of a contract command method's declared result, part of the
+ * contract (it surfaces in OpenAPI and every binding; proposal "Return values"):
+ *
+ * - `'void'` — fire-and-forget write (no body).
+ * - `'result'` — an outcome / status object (e.g. `{ ok, version }`).
+ * - `'entity'` — the updated entity (the post-write projection).
+ */
+type ContractCommandResult = 'void' | 'result' | 'entity';
+/** The Key of a contract: the field names that compose its access / join key. */
+interface ContractKeySpec {
+    /** The key field names, in declaration order (e.g. `["articleId"]`). */
+    readonly fields: readonly string[];
+}
+/**
+ * One External Query (Query Composition) binding on a contract query method
+ * (proposal "External Query"). It is a **build-time, in-process** read dependency
+ * on another contract referenced by name in the same SSoT — there is no protocol
+ * or transport. The runtime collects every parent key produced at this level and
+ * resolves the referenced contract **once, batched**, for all of them.
+ *
+ * A composed child MUST be `point` (proposal "N+1 Safety"): the parent step may
+ * yield N records, so a `range` child would be an N+1 fan-out.
+ */
+interface ComposeSpec {
+    /** The result property the composed value is attached to (e.g. `billing`). */
+    readonly as: string;
+    /** The referenced contract name (a symbol in the same SSoT). */
+    readonly contract: string;
+    /** The referenced method on that contract (e.g. `get`). */
+    readonly method: string;
+    /**
+     * An optional **logical** owner label (the bounded context that owns the
+     * referenced contract) — not a network address. Omitted when unlabeled.
+     */
+    readonly context?: string;
+    /**
+     * The child-key binding: child key field → a `from` source path on the parent
+     * result, e.g. `{ accountId: "$.billingAccountId" }`.
+     */
+    readonly bind: Readonly<Record<string, string>>;
+    /**
+     * The composed child's resolution. It MUST be `'point'` in a valid contract — a
+     * composed child coalesces to one `BatchGetItem` across all parent keys, so a
+     * `range` child (a partition `Query` that cannot be batched across the parent's
+     * keys) is an N+1 fan-out. The N+1 static checker (#60,
+     * {@link assertContractN1Safe}) rejects a `'range'` value on the build path; the
+     * field is widened to {@link ContractResolution} so the offending node can be
+     * carried into the assembled {@link ContractSpec} for the checker to inspect and
+     * reject with a clear message, rather than being silently unrepresentable.
+     */
+    readonly resolution: ContractResolution;
+    /** The composed child's per-key cardinality (`'one'` for a valid `point`). */
+    readonly cardinality: ContractCardinality;
+}
+/**
+ * The **composition execution plan** for one query contract method (issue #70a),
+ * the contract-layer mirror of {@link ExecutionPlanSpec}. It records how a method's
+ * External Query compositions (`compose[]`) are staged relative to the parent read
+ * and to one another, and the batching discipline each composed child obeys:
+ *
+ * - `stages` is an ordered list whose entries are indices into the method's
+ *   `compose[]`. The parent read (the referenced `operation`) is the implicit
+ *   stage before all of these. Every compose child binds its child key purely from
+ *   the **parent** result (`from('$.…')` paths), so sibling compositions are
+ *   mutually independent: they form a single stage `[0, 1, …]` and may be resolved
+ *   concurrently. (A composed child cannot, today, bind from another composed
+ *   child — the #63 DSL only exposes parent `from` paths — so there is never a
+ *   cross-composition dependency; the field is a list of stages so the shape can
+ *   carry one if a future primitive introduces it.)
+ * - `concurrency` is the declared in-flight bound applied **within** a stage (the
+ *   shared {@link RELATION_TRAVERSAL_CONCURRENCY} = 16).
+ * - `batchChunkSize` is the per-request key cap for a composed child read (100,
+ *   the DynamoDB `BatchGetItem` limit): a composition resolves **one batched
+ *   call** across all parent records (chunked at this size), never an N+1 fan-out
+ *   (the composed child is `point`, enforced by the #60 N+1 checker).
+ *
+ * Emitted only when the method declares at least one composition. A method without
+ * compositions carries no plan, and a runtime without one resolves any
+ * compositions sequentially (the pre-#70 behavior) — so an absent plan never
+ * changes results.
+ */
+interface CompositionPlanSpec {
+    /** Ordered stages of indices into `compose[]` (independent siblings share a stage). */
+    readonly stages: readonly (readonly number[])[];
+    /** The declared in-flight bound applied within each composition stage (16). */
+    readonly concurrency: number;
+    /** Per-request key cap for a composed child's batched read (100, BatchGetItem limit). */
+    readonly batchChunkSize: number;
+}
+/**
+ * The serialized spec of one **query** contract method. Carries the decided facts
+ * (`resolution` / `inputArity` / `cardinality`) the planner derived in #58, a
+ * reference into `queries` by name (the internal op), and any External Query
+ * compositions. The decided facts are **serialized, not re-derived** — every
+ * runtime honors them.
+ */
+interface QueryContractMethodSpec {
+    /** Derived: `'point'` (unique-key query) or `'range'` (partition list). */
+    readonly resolution: ContractResolution;
+    /** Derived: `'either'` for `point`, `'single'` for `range`. */
+    readonly inputArity: ContractInputArity;
+    /** Derived per-key result shape: `'one'` (point) or `'many'` (range). */
+    readonly cardinality: ContractCardinality;
+    /** The referenced read op name in `queries` (e.g. `ArticleById__get`). */
+    readonly operation: string;
+    /** External Query compositions on this method; omitted when there are none. */
+    readonly compose?: readonly ComposeSpec[];
+    /**
+     * The composition staging + batch plan (issue #70a); present only when `compose`
+     * is. See {@link CompositionPlanSpec}: independent compositions form one
+     * concurrency-eligible stage after the parent read, each resolved as one batched
+     * call (chunk ≤100). Absent → resolve compositions sequentially (pre-#70).
+     */
+    readonly compositionPlan?: CompositionPlanSpec;
+    /**
+     * Optional human-readable description of the read use case (issue #154), from the
+     * descriptor's `description`. Pure documentation — absent unless declared, so a
+     * method with no description serializes byte-identically to the pre-#154 spec.
+     * The same string appears in the TS contract IR and (via the SSoT) in any
+     * generated binding, so TS↔Python carry an identical description.
+     */
+    readonly description?: string;
+}
+/**
+ * How a contract command method resolves a single key vs. an array of keys to the
+ * underlying write surface (proposal "Consistency with the existing write
+ * surface"). A single key → one write op (or one transaction); an array → a
+ * batched write — a `TransactWriteItems` when atomicity / per-item conditions are
+ * required, or a `BatchWriteItem` when neither is.
+ */
+type CommandResolutionTarget = 
+/** One write op, referenced by name in `commands`. */
+{
+    readonly mode: 'op';
+    readonly operation: string;
+}
+/** One transaction, referenced by name in `transactions`. */
+ | {
+    readonly mode: 'transaction';
+    readonly transaction: string;
+}
+/**
+ * A non-atomic **parallel** fan-out over the per-key write op (#101). The op
+ * MAY carry a condition (guarded create / conditioned update). Unconditioned
+ * `put`/`delete` ops coalesce into a `BatchWriteItem` (with `UnprocessedItems`
+ * retry); conditioned/update ops issue individual conditional writes
+ * concurrently. Per-op success/failure is reported (partial success); a
+ * per-op failure never aborts the others. References the per-key write op in
+ * `commands`.
+ */
+ | {
+    readonly mode: 'parallel';
+    readonly operation: string;
+};
+/**
+ * The serialized spec of one **command** contract method. Symmetric to
+ * {@link QueryContractMethodSpec}: it carries the declared `result` type and the
+ * `single` / `batch` resolution targets into the existing write specs.
+ */
+interface CommandContractMethodSpec {
+    /** Derived input arity: writes accept `'either'` (single key or key array). */
+    readonly inputArity: ContractInputArity;
+    /** The declared result type (`void` | a `Result` | the updated entity). */
+    readonly result: ContractCommandResult;
+    /** How a single key resolves (one op / one transaction). */
+    readonly single: CommandResolutionTarget;
+    /**
+     * How an array of keys resolves (a transaction / `BatchWriteItem`); omitted
+     * when the contract does not declare a batched write form.
+     */
+    readonly batch?: CommandResolutionTarget;
+    /**
+     * The **return projection** of a `mutation`-derived command method (issue #83;
+     * proposal §3, "return selection as a read projection"). A JSON-safe boolean
+     * field map: after the write commits, the runtime issues a **`GetItem` with
+     * `ConsistentRead`** of the written entity's primary key and applies this
+     * projection via the existing read-projection machinery, returning the projected
+     * item. This is the **uniform** return mechanism for both a single-op command
+     * and a future transaction (a `TransactWriteItems` cannot return item images),
+     * so TS and Python return an **identical** projected item.
+     *
+     * The consistent read-back is issued against the read op named
+     * `<Contract>__<method>__readback` (a synthesized {@link QuerySpec}: a `GetItem`
+     * on the written entity's primary key projecting these fields). Present only on
+     * a `.plan(mutation)` method; a hand-written #64 command omits it (its
+     * {@link result} stays `'void'` / `'entity'` and it returns no projected item).
+     */
+    readonly returnSelection?: Readonly<Record<string, boolean>>;
+    /**
+     * Optional SCP expression guard on the contract-method op (issue #261,
+     * Phase 3 S1) — the same guard slot a {@link TransactionItemSpec} carries:
+     * a boolean behavior-contracts Expression IR expression gating the method's
+     * write. Vocabulary-only in S1 (populated by the #262 lowerer); a document
+     * carrying it is stamped {@link SPEC_VERSION_SCP} (`1.2`) so pre-evaluation
+     * runtimes loud-reject it (fail-closed).
+     */
+    readonly guard?: ExpressionSpec;
+    /**
+     * Optional human-readable description of the write use case (issue #154), from
+     * the descriptor's `description`. Pure documentation — absent unless declared, so
+     * a method with no description serializes byte-identically to the pre-#154 spec.
+     */
+    readonly description?: string;
+}
+/**
+ * A serialized contract — a keyed public read (`'query'`) or write (`'command'`)
+ * interface holding one or more named methods. Each method references an existing
+ * operation spec by name and adds the decided contract facts. The existing
+ * operation-spec shapes are unchanged, so the current runtime keeps working.
+ */
+interface ContractSpec {
+    /** Whether this is a read (`'query'`) or write (`'command'`) contract. */
+    readonly kind: ContractKind;
+    /** The contract Key (the access pattern / join / batch key). */
+    readonly key: ContractKeySpec;
+    /**
+     * The named methods (use cases over the same Key). A query contract's methods
+     * are {@link QueryContractMethodSpec}; a command contract's are
+     * {@link CommandContractMethodSpec}. The map is keyed by contract `kind`.
+     */
+    readonly methods: Readonly<Record<string, QueryContractMethodSpec>> | Readonly<Record<string, CommandContractMethodSpec>>;
+}
+/**
+ * One bounded context's membership (issue #59, "context ownership"). Lists the
+ * Models and Contracts that belong to the same context, so the future boundary
+ * lint (#61) can tell **own** from **foreign**: a contract may resolve its own
+ * context's Models directly, but may only reach another context through that
+ * context's published Contract (direct use of a foreign Model is a build error).
+ *
+ * This issue only **serializes / emits** this declaration; it does not enforce
+ * it. Both lists are entity / contract *names* (matching `manifest.entities` keys
+ * and `contracts` keys respectively).
+ */
+interface ContextSpec {
+    /** Model (entity) names owned by this context (sorted; manifest entity keys). */
+    readonly models: readonly string[];
+    /** Contract names owned by this context (sorted; `contracts` map keys). */
+    readonly contracts: readonly string[];
+}
+interface OperationsDocument {
+    /**
+     * `1.1` unless the document actually contains an SCP Expression IR node (a
+     * `scpExpr` condition or a `guard`), in which case it is stamped `1.2`
+     * (issue #261, conditional stamping — see {@link SPEC_VERSION_SCP}).
+     */
+    readonly version: SpecVersion;
+    readonly queries: Readonly<Record<string, QuerySpec>>;
+    readonly commands: Readonly<Record<string, CommandSpec>>;
+    /** Declarative transactions (issue #46). Absent in pre-#46 specs. */
+    readonly transactions?: Readonly<Record<string, TransactionSpec>>;
+    /**
+     * The CQRS Contract layer (issue #59): contract name → {@link ContractSpec}.
+     * Layered **on top of** the existing `queries` / `commands` / `transactions`
+     * (each method references one of them by name). **Absent** when the input
+     * defines no contracts — so a contract-free input produces a byte-identical
+     * pre-#59 operations document (backward compatibility).
+     */
+    readonly contracts?: Readonly<Record<string, ContractSpec>>;
+    /**
+     * Context-ownership declarations (issue #59): context name →
+     * {@link ContextSpec}. Used by the boundary lint (#61) to tell own from
+     * foreign. **Absent** when no contexts are declared (backward compatibility).
+     */
+    readonly contexts?: Readonly<Record<string, ContextSpec>>;
+}
+/** The full `{ manifest, operations }` bundle produced by the static planner. */
+interface BridgeBundle {
+    readonly manifest: Manifest;
+    readonly operations: OperationsDocument;
+}
+
+export { type WriteOperationType as $, type ExpressionScalar as A, type BridgeBundle as B, type ContractSpec as C, type ManifestEntity as D, type ExpressionSpec as E, type FilterSpec as F, type ManifestField as G, type ManifestFieldType as H, type ManifestGsi as I, type ManifestKey as J, type ManifestRelation as K, type ManifestTable as L, type Manifest as M, type OperationSpec as N, type OperationsDocument as O, type ParamSpec as P, type QuerySpec as Q, type QueryContractMethodSpec as R, SPEC_VERSION as S, type TransactionSpec as T, type RangeConditionSpec as U, type ReadOperationType as V, SPEC_VERSION_SCP as W, SPEC_VERSION_SUPPORTED as X, type TransactionItemSpec as Y, type TransactionItemType as Z, type WhenSpec as _, type CommandSpec as a, type ParamKind as a0, type LiteralParam as a1, type NumberParam as a2, type StringParam as a3, isParam as a4, param as a5, type ContextSpec as b, type Param as c, type ConditionSpec as d, type SpecVersion as e, type CommandContractMethodSpec as f, type CommandResolutionTarget as g, type ComposeSpec as h, type CompositionPlanSpec as i, type ContractCardinality as j, type ContractCommandResult as k, type ContractInputArity as l, type ContractKeySpec as m, type ContractKind as n, type ContractResolution as o, EXPR_VERSION as p, type ExecutionPlanSpec as q, type ExpressionArrNode as r, type ExpressionFloatNode as s, type ExpressionIntNode as t, type ExpressionNode as u, type ExpressionObjNode as v, type ExpressionOpNode as w, type ExpressionOperator as x, type ExpressionRefNode as y, type ExpressionRefOptNode as z };