graphddb 0.2.0 → 0.2.1

package/dist/index.js

@@ -28,7 +28,7 @@ import {
   compileFragment,
   compileMutationPlan,
   compileSingleFragmentPlan,
-  cond,
+  conditionParamName,
   contractOfMethodSpec,
   decodeCursor,
   definePlan,
@@ -68,7 +68,6 @@ import {
   isLifecycleContract,
   isMutationFragment,
   isMutationInputRef,
-  isParam,
   isPlannedCommandMethod,
   isQueryModelContract,
   isSelectBuilder,
@@ -78,7 +77,6 @@ import {
   mintContractKeyFieldRef,
   mintContractParamRef,
   mutation,
-  param,
   plan,
   publicCommandModel,
   publicQueryModel,
@@ -88,11 +86,11 @@ import {
   validateDepth,
   when,
   wholeKeysSentinel
-} from "./chunk-F27INYI2.js";
+} from "./chunk-4B4MUPUJ.js";
 import {
   CdcEmulator,
   createCdcEmulator
-} from "./chunk-UNRQ5YJT.js";
+} from "./chunk-SBNP62H7.js";
 import {
   BATCH_GET_MAX_KEYS,
   BATCH_WRITE_MAX_ITEMS,
@@ -110,7 +108,9 @@ import {
   buildUpdateExpression,
   buildUpdateInput,
   collapseSameKeyItems,
+  collectRawConditionParams,
   commitTransaction,
+  cond,
   createDefaultLinter,
   execItemKeySignature,
   executeDelete,
@@ -121,16 +121,20 @@ import {
   gsiAmbiguityRule,
   isColumn,
   isKeySegment,
+  isParam,
+  isRawCondition,
   k,
   key,
   missingGsiRule,
   noScanRule,
+  param,
   relationDepthRule,
   requireLimitRule,
+  resolveConditionTree,
   resolveKey,
   resolveModelClass,
   serializeFieldValue
-} from "./chunk-347U24SB.js";
+} from "./chunk-PWV7JDMR.js";
 
 // src/metadata/prefix.ts
 function derivePrefix(customPrefix, className) {
@@ -413,6 +417,12 @@ function whenHolds(when2, params, element) {
   const right = resolveTemplate(when2.right, params, element);
   return when2.op === "eq" ? left === right : left !== right;
 }
+function resolveRawConditionValue(val, params, element) {
+  if (val !== null && typeof val === "object" && typeof val.$param === "string") {
+    return resolveValue(`{${val.$param}}`, params, element);
+  }
+  return val;
+}
 function applyCondition(condition, target, params, element) {
   if (!condition) return;
   const names = target.ExpressionAttributeNames ??= {};
@@ -428,6 +438,25 @@ function applyCondition(condition, target, params, element) {
     return;
   }
   const values = target.ExpressionAttributeValues ??= {};
+  if (condition.kind === "raw") {
+    Object.assign(names, condition.names);
+    for (const [alias, val] of Object.entries(condition.values)) {
+      values[alias] = resolveRawConditionValue(val, params, element);
+    }
+    target.ConditionExpression = condition.expression;
+    return;
+  }
+  if (condition.kind === "expr") {
+    const concrete = resolveConditionTree(
+      condition.declarative,
+      (name) => resolveValue(`{${name}}`, params, element)
+    );
+    const compiled = buildConditionExpression(concrete);
+    Object.assign(names, compiled.names);
+    Object.assign(values, compiled.values);
+    target.ConditionExpression = compiled.expression;
+    return;
+  }
   const clauses = [];
   let i = 0;
   for (const [field2, tmpl] of Object.entries(condition.fields)) {
@@ -832,11 +861,88 @@ function entityRef(model2) {
 }
 function collectConditionParams(condition, out) {
   if (condition === void 0) return;
+  if (isRawCondition(condition)) {
+    for (const { name, param: param2 } of collectRawConditionParams(condition)) {
+      out[name] = descriptorFromParam(name, param2, out[name]);
+    }
+    return;
+  }
   const obj = condition;
   if (obj.notExists === true) return;
   if (typeof obj.attributeExists === "string") return;
   if (typeof obj.attributeNotExists === "string") return;
-  collectParams(condition, out);
+  collectConditionTreeParams(obj, out);
+}
+var SINGLE_OPERAND_OPS = /* @__PURE__ */ new Set([
+  "eq",
+  "ne",
+  "gt",
+  "ge",
+  "lt",
+  "le",
+  "beginsWith",
+  "contains",
+  "notContains",
+  "attributeType",
+  "size"
+]);
+function collectConditionTreeParams(obj, out) {
+  for (const [key2, value] of Object.entries(obj)) {
+    if (value === void 0) continue;
+    if (key2 === "and" || key2 === "or") {
+      for (const sub of value) {
+        if (isRawCondition(sub)) {
+          for (const { name, param: param2 } of collectRawConditionParams(sub)) {
+            out[name] = descriptorFromParam(name, param2, out[name]);
+          }
+          continue;
+        }
+        collectConditionTreeParams(sub, out);
+      }
+      continue;
+    }
+    if (key2 === "not") {
+      if (isRawCondition(value)) {
+        for (const { name, param: param2 } of collectRawConditionParams(value)) {
+          out[name] = descriptorFromParam(name, param2, out[name]);
+        }
+        continue;
+      }
+      collectConditionTreeParams(value, out);
+      continue;
+    }
+    if (isParam(value)) {
+      out[key2] = descriptorFromParam(key2, value, out[key2]);
+      continue;
+    }
+    if (value === null || typeof value !== "object" || value instanceof Date) {
+      continue;
+    }
+    const ops = value;
+    for (const [op, opVal] of Object.entries(ops)) {
+      if (op === "between") {
+        const [lo, hi] = opVal;
+        if (isParam(lo)) {
+          const n = conditionParamName(key2, op, 0);
+          out[n] = descriptorFromParam(n, lo, out[n]);
+        }
+        if (isParam(hi)) {
+          const n = conditionParamName(key2, op, 1);
+          out[n] = descriptorFromParam(n, hi, out[n]);
+        }
+      } else if (op === "in") {
+        opVal.forEach((v, i) => {
+          if (isParam(v)) {
+            const n = conditionParamName(key2, op, i);
+            out[n] = descriptorFromParam(n, v, out[n]);
+          }
+        });
+      } else if (SINGLE_OPERAND_OPS.has(op) && isParam(opVal)) {
+        const n = conditionParamName(key2, op);
+        out[n] = descriptorFromParam(n, opVal, out[n]);
+      }
+    }
+  }
 }
 function makeDefinition(model2, operation, key2, select, changes, condition) {
   const params = collectParams(key2);

package/dist/testing/index.d.ts

@@ -1,4 +1,4 @@
-import { E as Executor, D as DynamoDBOperation, a as ExecutorResult, B as BatchGetExecInput, P as PutInput, W as WriteExecOptions, b as WriteResult, U as UpdateInput, c as DeleteInput, d as BatchWriteExecItem, T as TransactWriteExecItem, M as ModelStatic, e as DDBModel, C as ChangeEvent } from '../types-D6qLpw2M.js';
+import { E as Executor, D as DynamoDBOperation, a as ExecutorResult, B as BatchGetExecInput, P as PutInput, W as WriteExecOptions, b as WriteResult, U as UpdateInput, c as DeleteInput, d as BatchWriteExecItem, T as TransactWriteExecItem, M as ModelStatic, e as DDBModel, C as ChangeEvent } from '../types-DPJ4tPjX.js';
 import '@aws-sdk/client-dynamodb';
 
 /**

package/dist/testing/index.js

@@ -1,12 +1,12 @@
 import {
   createCdcEmulator
-} from "../chunk-UNRQ5YJT.js";
+} from "../chunk-SBNP62H7.js";
 import {
   ClientManager,
   MetadataRegistry,
   TableMapping,
   resolveModelClass
-} from "../chunk-347U24SB.js";
+} from "../chunk-PWV7JDMR.js";
 
 // src/memory/memory-store.ts
 function deepClone(value) {

package/dist/{types-D6qLpw2M.d.ts → types-DPJ4tPjX.d.ts}

@@ -52,6 +52,113 @@ type ResolvedKey = {
     inputFieldNames: string[];
 };
 
+/**
+ * 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>>>;
+}
+/** 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`. */
+type ArrayParam<E extends ArrayElementShape> = Param<ElementOf<E>[]> & {
+    readonly element: E;
+};
+/** Allowed scalar value types a placeholder may stand in for. */
+type ParamValue = string | number;
+/**
+ * Placeholder factory. Each call returns a branded {@link Param} carrying both
+ * the TypeScript value type and a runtime descriptor.
+ */
+declare const param: {
+    /** A placeholder for a `string` value. */
+    readonly string: () => StringParam;
+    /** A placeholder for a `number` value. */
+    readonly number: () => 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.
+     *
+     * @example
+     * ```ts
+     * param.literal('active', 'disabled'); // Param<'active' | 'disabled'>
+     * ```
+     */
+    readonly literal: <const L extends readonly [ParamValue, ...ParamValue[]]>(...values: L) => 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) => ArrayParam<E>;
+};
+/** Runtime type guard: is `value` a parameter placeholder? */
+declare function isParam(value: unknown): value is Param<unknown>;
+
 /**
  * Internal brand identifying a {@link RawCondition} produced by {@link cond}.
  */
@@ -85,7 +192,7 @@ interface RawCondition<M = unknown> {
  * @typeParam M - The owning model brand. Constrains all columns to one model,
  *   so passing another model's column is a compile error.
  */
-type CondSlot<M> = Column<any, M> | string | number | boolean | Date;
+type CondSlot<M> = Column<any, M> | string | number | boolean | Date | Param<unknown>;
 /**
  * Raw DynamoDB condition escape hatch.
  *
@@ -197,6 +304,35 @@ type FilterInput<T> = ({
     or?: readonly (FilterInput<T> | RawCondition<T>)[];
     not?: FilterInput<T> | RawCondition<T>;
 }) | RawCondition<T>;
+/**
+ * A type-safe **write condition** for `putItem` / `updateItem` / `deleteItem`
+ * and a transaction item (issue #114-A). Structurally the declarative operator
+ * subset of {@link FilterInput} — the same per-field-type operator constraints
+ * (e.g. `beginsWith` on a numeric field is a compile error) — plus the legacy
+ * existence primitives (`{ notExists }` / `{ attributeExists }` /
+ * `{ attributeNotExists }`). The raw `cond` escape hatch (issue #114-B) is also
+ * accepted — as a whole condition or as a member of an `and` / `or` / `not`
+ * group — for conditions the declarative subset cannot express; its
+ * `Model.col.<field>` brand must match the write target model `T`
+ * (injection-free / refactor-safe), exactly as on the read side.
+ */
+type WriteCondition<T> = ({
+    [K in ScalarKeys<T>]?: FieldFilter<T[K]>;
+} & {
+    /** Legacy whole-row guard: `attribute_not_exists(PK)`. */
+    notExists?: true;
+    /** `attribute_exists(<field>)` — the named attribute must be present. */
+    attributeExists?: string;
+    /** `attribute_not_exists(<field>)` — the named attribute must be absent. */
+    attributeNotExists?: string;
+    and?: readonly (WriteCondition<T> | RawCondition<T>)[];
+    or?: readonly (WriteCondition<T> | RawCondition<T>)[];
+    not?: WriteCondition<T> | RawCondition<T>;
+}) | RawCondition<T>;
+/** Options carrying an optional type-safe write {@link WriteCondition}. */
+interface WriteOptions<T> {
+    readonly condition?: WriteCondition<T>;
+}
 
 /**
  * Internal brand symbol identifying a compiled select builder at runtime.
@@ -700,7 +836,7 @@ interface ModelStatic<T extends DDBModel, C = unknown> {
         consistentRead?: boolean;
         filter?: FilterInput<T>;
     }): ExecutionPlan;
-    putItem(item: EntityInput<T>, options?: Record<string, unknown>): Promise<void>;
+    putItem(item: EntityInput<T>, options?: WriteOptions<T>): Promise<void>;
     /**
      * Update an item identified by its **explicit base-table primary key**
      * (`PrimaryKeyOf<C>`). This is the canonical form — it requires the key input
@@ -708,7 +844,7 @@ interface ModelStatic<T extends DDBModel, C = unknown> {
      *
      * @example `await User.updateItem({ userId: 'alice' }, { status: 'disabled' });`
      */
-    updateItem(key: UpdateExplicitKey<C>, changes: Partial<T>, options?: Record<string, unknown>): Promise<void>;
+    updateItem(key: UpdateExplicitKey<C>, changes: Partial<T>, options?: WriteOptions<T>): Promise<void>;
     /**
      * Update an item using an **updatable** entity obtained from
      * `query(..., { updatable: true })` / `list(..., { updatable: true })`. The
@@ -719,18 +855,18 @@ interface ModelStatic<T extends DDBModel, C = unknown> {
      * brand (rejected here at compile time) and the hidden key (rejected at
      * runtime), preventing an accidental wrong-item update.
      */
-    updateItem(entity: Partial<T> & Updatable, changes: Partial<T>, options?: Record<string, unknown>): Promise<void>;
-    deleteItem(key: DeleteKey<C>, options?: Record<string, unknown>): Promise<void>;
+    updateItem(entity: Partial<T> & Updatable, changes: Partial<T>, options?: WriteOptions<T>): Promise<void>;
+    deleteItem(key: DeleteKey<C>, options?: WriteOptions<T>): Promise<void>;
 }
 
-interface PutOptions {
-    condition?: Record<string, unknown>;
+interface PutOptions<T = unknown> {
+    condition?: WriteCondition<T>;
 }
-interface UpdateOptions {
-    condition?: Record<string, unknown>;
+interface UpdateOptions<T = unknown> {
+    condition?: WriteCondition<T>;
 }
-interface DeleteOptions {
-    condition?: Record<string, unknown>;
+interface DeleteOptions<T = unknown> {
+    condition?: WriteCondition<T>;
 }
 
 interface PutInput {
@@ -949,113 +1085,6 @@ declare class BatchGetResult {
 declare function executeBatchGet(requests: BatchGetRequest[]): Promise<BatchGetResult>;
 declare function executeBatchWrite(requests: BatchWriteRequest[]): Promise<void>;
 
-/**
- * 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>>>;
-}
-/** 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`. */
-type ArrayParam<E extends ArrayElementShape> = Param<ElementOf<E>[]> & {
-    readonly element: E;
-};
-/** Allowed scalar value types a placeholder may stand in for. */
-type ParamValue = string | number;
-/**
- * Placeholder factory. Each call returns a branded {@link Param} carrying both
- * the TypeScript value type and a runtime descriptor.
- */
-declare const param: {
-    /** A placeholder for a `string` value. */
-    readonly string: () => StringParam;
-    /** A placeholder for a `number` value. */
-    readonly number: () => 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.
-     *
-     * @example
-     * ```ts
-     * param.literal('active', 'disabled'); // Param<'active' | 'disabled'>
-     * ```
-     */
-    readonly literal: <const L extends readonly [ParamValue, ...ParamValue[]]>(...values: L) => 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) => ArrayParam<E>;
-};
-/** Runtime type guard: is `value` a parameter placeholder? */
-declare function isParam(value: unknown): value is Param<unknown>;
-
 /**
  * Intermediate representation (IR) produced by the parameterized definition DSL
  * (issue #41). This is the **in-memory, typed** representation consumed by the
@@ -1092,18 +1121,48 @@ type OperationKind = 'query' | 'list' | 'put' | 'update' | 'delete';
  * - `{ field: value, … }` → field equality (`#f = :v AND …`). Each value may be
  *   a concrete literal **or** a {@link Param} placeholder (bound at execution).
  *
- * The forms are mutually exclusive: `notExists` / `attributeExists` /
+ * The existence forms are mutually exclusive: `notExists` / `attributeExists` /
  * `attributeNotExists` are single-primitive conditions and ignore any sibling
  * fields. (When more than one would be present the most specific is taken in the
  * order `notExists` → `attributeExists` → `attributeNotExists`.)
- */
+ *
+ * Beyond bare equality, a field value may be a declarative **operator object**
+ * (issue #114-A) — `{ gt }`, `{ between }`, `{ in }`, `{ beginsWith }`, … —
+ * mirroring the read-side `FilterInput`, and the reserved `and` / `or` (arrays)
+ * / `not` (single nested condition) keys express logical groups. Each operand
+ * value may be a concrete literal or a {@link Param} placeholder.
+ */
+type ConditionLeaf = Param<unknown> | string | number | boolean | Date;
+/** A declarative operator object on one condition field (subset of FilterInput). */
+interface ConditionOperatorObject {
+    readonly eq?: ConditionLeaf;
+    readonly ne?: ConditionLeaf;
+    readonly gt?: ConditionLeaf;
+    readonly ge?: ConditionLeaf;
+    readonly lt?: ConditionLeaf;
+    readonly le?: ConditionLeaf;
+    readonly between?: readonly [ConditionLeaf, ConditionLeaf];
+    readonly in?: readonly ConditionLeaf[];
+    readonly beginsWith?: ConditionLeaf;
+    readonly contains?: ConditionLeaf;
+    readonly notContains?: ConditionLeaf;
+    readonly attributeExists?: boolean;
+    readonly attributeType?: string;
+}
 type ConditionInput = {
     readonly notExists: true;
 } | {
     readonly attributeExists: string;
 } | {
     readonly attributeNotExists: string;
-} | Readonly<Record<string, Param<unknown> | string | number | boolean>>;
+} | RawCondition | ConditionTree;
+/** A recursive declarative condition tree (field clauses + logical groups). */
+interface ConditionTree {
+    readonly and?: readonly ConditionInput[];
+    readonly or?: readonly ConditionInput[];
+    readonly not?: ConditionInput;
+    readonly [field: string]: ConditionLeaf | ConditionOperatorObject | readonly ConditionInput[] | ConditionInput | undefined;
+}
 /** Options accepted by the write `define*` entry points (issue #46). */
 interface WriteDefinitionOptions {
     /** Optional declarative write condition (subset). */
@@ -1954,6 +2013,16 @@ type WriteOperationType = 'PutItem' | 'UpdateItem' | 'DeleteItem';
  *   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';
@@ -1966,6 +2035,30 @@ type ConditionSpec = {
 } | {
     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>>;
 };
 interface CommandSpec {
     readonly type: WriteOperationType;
@@ -4511,4 +4604,4 @@ interface CdcEmulatorOptions {
 }
 type ShardId = string;
 
-export { type BridgeBundle as $, type EntityInput as A, type BatchGetExecInput as B, type ChangeEvent as C, type DynamoDBOperation as D, type Executor as E, type FaultSpec as F, type UniqueQueryKeyOf as G, type EntityRef as H, type ConditionInput as I, type QueryMethodSpec as J, type CommandModelContract as K, type CommandMethodSpec as L, type ModelStatic as M, type ContractSpec as N, type OperationDefinition as O, type PutInput as P, type QueryModelContract as Q, type ResolvedKey as R, type SelectableOf as S, type TransactWriteExecItem as T, type UpdateInput as U, type QuerySpec as V, type WriteExecOptions as W, type CommandSpec as X, type ContextSpec as Y, type OperationsDocument as Z, type AnyOperationDefinition as _, type ExecutorResult as a, type InputArity as a$, type ConditionSpec as a0, type BatchDeleteRequest as a1, type BatchGetRequest as a2, BatchGetResult as a3, type BatchPutRequest as a4, type BatchResult as a5, type BatchWriteRequest as a6, CONTRACT_RANGE_FANOUT_CONCURRENCY as a7, type CdcMode as a8, type ChangeBatch as a9, type ContractKeyRef as aA, type ContractKeySpec as aB, type ContractKind as aC, type ContractMethodOp as aD, type ContractParamRef as aE, type ContractQueryParams as aF, type ContractResolution as aG, type DeleteOptions as aH, type DeriveEffect as aI, type DerivedEdgeWrite as aJ, type DerivedUpdate as aK, type DescriptorBinding as aL, ENTITY_WRITES_MARKER as aM, type EdgeEffect as aN, type EffectPath as aO, type EmitEffect as aP, type EntityWritesDefinition as aQ, type EntityWritesShape as aR, type ExecutableCommandContract as aS, type ExecutableQueryContract as aT, type FilterInput as aU, type FilterSpec as aV, type FragmentInput as aW, type GsiDefinitionMarker as aX, type GsiOptions as aY, type IdempotencyEffect as aZ, type InProcessWriteDescriptor as a_, type ChangeEventName as aa, type ClockMode as ab, type Column as ac, type ColumnMap as ad, type CommandContractMethodSpec as ae, type CommandInputShape as af, type CommandMethod as ag, type CommandPlan as ah, type CommandResolutionTarget as ai, type CommandResultKind as aj, type CommandSelectShape as ak, type CompiledFragment as al, type ComposeSpec as am, type CondSlot as an, type ConditionCheckInput as ao, type Connection as ap, type ContractCallSignature as aq, type ContractCardinality as ar, type ContractCommandParams as as, type ContractCommandResult as at, type ContractComposeNode as au, type ContractFromRef as av, type ContractInputArity as aw, type ContractItem as ax, type ContractKeyFieldRef as ay, type ContractKeyInput as az, type WriteResult as b, type UniqueEffect as b$, type KeyDefinitionMarker as b0, type KeySegment as b1, type KeySlot as b2, type KeyStructure as b3, type KeyedResult as b4, LIFECYCLE_CONTRACT_MARKER as b5, type LifecycleContract as b6, type LifecycleEffects as b7, type LiteralParam as b8, type ManifestEntity as b9, type QueryContractMethodSpec as bA, type QueryEnvelopeResult as bB, type QueryKeyOf as bC, type QueryMethod as bD, type QueryResult as bE, type RangeConditionSpec as bF, type RawCondition as bG, type ReadEnvelope as bH, type ReadOperationType as bI, type ReadRouteDescriptor as bJ, type ReadRouteOptions as bK, type ReadRouteResult as bL, type RecordedCompose as bM, type RelationBuilder as bN, type RelationSelect as bO, type RelationSpec as bP, type RequiresEffect as bQ, type Resolution as bR, SPEC_VERSION as bS, type SegmentSpec as bT, type SelectBuilder as bU, type SelectOf as bV, type StartingPosition as bW, type StreamViewType as bX, type StringParam as bY, TransactionContext as bZ, type TransactionItemType as b_, type ManifestField as ba, type ManifestFieldType as bb, type ManifestGsi as bc, type ManifestKey as bd, type ManifestRelation as be, type ManifestTable as bf, type ModelRef as bg, type MutateMode as bh, type MutateOptions as bi, type MutateParallelResult as bj, type MutateTransactionResult as bk, type MutationBody as bl, type MutationDescriptorMap as bm, type MutationFragment as bn, type MutationInputProxy as bo, type MutationInputRef as bp, type MutationIntent as bq, type NumberParam as br, type OperationKind as bs, type OperationSpec as bt, type ParallelOpResult as bu, type ParamKind as bv, type ParamSpec as bw, type ParamStructure as bx, type PlannedCommandMethod as by, type PutOptions as bz, type DeleteInput as c, type Updatable as c0, type UpdateOptions as c1, type WhenSpec as c2, type WriteDescriptor as c3, type WriteEnvelope as c4, type WriteLifecyclePhase as c5, type WriteOperationType as c6, type WriteRecorder as c7, type WriteResultProjection as c8, attachModelClass as c9, isContractComposeNode as cA, isContractFromRef as cB, isContractKeyFieldRef as cC, isContractKeyRef as cD, isContractParamRef as cE, isEntityWritesDefinition as cF, isKeySegment as cG, isLifecycleContract as cH, isMutationFragment as cI, isMutationInputRef as cJ, isParam as cK, isPlannedCommandMethod as cL, isQueryModelContract as cM, k as cN, key as cO, lifecyclePhaseForIntent as cP, mintContractKeyFieldRef as cQ, mintContractParamRef as cR, mutation as cS, param as cT, publicCommandModel as cU, publicQueryModel as cV, query as cW, resolveLifecycle as cX, wholeKeysSentinel as cY, buildDeleteInput as ca, buildPutInput as cb, buildUpdateInput as cc, compileFragment as cd, compileMutationPlan as ce, compileSingleFragmentPlan as cf, cond as cg, contractOfMethodSpec as ch, definePlan as ci, entityWrites as cj, executeBatchGet as ck, executeBatchWrite as cl, executeCommandMethod as cm, executeDelete as cn, executeKeyedBatchGet as co, executePut as cp, executeQueryMethod as cq, executeRangeFanout as cr, executeTransaction as cs, executeUpdate as ct, from as cu, getEntityWrites as cv, gsi as cw, isColumn as cx, isCommandModelContract as cy, isCommandPlan as cz, type BatchWriteExecItem as d, DDBModel as e, type PrimaryKeyOf as f, type ExecutionPlanSpec as g, type SegmentedKey as h, type SelectBuilderSpec as i, type TransactionSpec as j, type Manifest as k, type ExecutionPlan as l, type CdcEmulatorOptions as m, type ChangeHandler as n, type Unsubscribe as o, type ConcurrentRecomputeRef as p, type EventLog as q, type ReplayOptions as r, type ShardId as s, type TransactionItemSpec as t, type Param as u, type ParamDescriptor as v, type DefinitionMap as w, type WriteDefinitionOptions as x, type PartialQueryKeyOf as y, type StrictSelectSpec as z };
+export { type AnyOperationDefinition as $, type StrictSelectSpec as A, type BatchGetExecInput as B, type ChangeEvent as C, type DynamoDBOperation as D, type Executor as E, type FaultSpec as F, type EntityInput as G, type UniqueQueryKeyOf as H, type EntityRef as I, type ConditionInput as J, type QueryMethodSpec as K, type CommandModelContract as L, type ModelStatic as M, type CommandMethodSpec as N, type OperationDefinition as O, type PutInput as P, type QueryModelContract as Q, type RawCondition as R, type SelectableOf as S, type TransactWriteExecItem as T, type UpdateInput as U, type ContractSpec as V, type WriteExecOptions as W, type QuerySpec as X, type CommandSpec as Y, type ContextSpec as Z, type OperationsDocument as _, type ExecutorResult as a, type InProcessWriteDescriptor as a$, type BridgeBundle as a0, type ConditionSpec as a1, type BatchDeleteRequest as a2, type BatchGetRequest as a3, BatchGetResult as a4, type BatchPutRequest as a5, type BatchResult as a6, type BatchWriteRequest as a7, CONTRACT_RANGE_FANOUT_CONCURRENCY as a8, type CdcMode as a9, type ContractKeyInput as aA, type ContractKeyRef as aB, type ContractKeySpec as aC, type ContractKind as aD, type ContractMethodOp as aE, type ContractParamRef as aF, type ContractQueryParams as aG, type ContractResolution as aH, type DeleteOptions as aI, type DeriveEffect as aJ, type DerivedEdgeWrite as aK, type DerivedUpdate as aL, type DescriptorBinding as aM, ENTITY_WRITES_MARKER as aN, type EdgeEffect as aO, type EffectPath as aP, type EmitEffect as aQ, type EntityWritesDefinition as aR, type EntityWritesShape as aS, type ExecutableCommandContract as aT, type ExecutableQueryContract as aU, type FilterInput as aV, type FilterSpec as aW, type FragmentInput as aX, type GsiDefinitionMarker as aY, type GsiOptions as aZ, type IdempotencyEffect as a_, type ChangeBatch as aa, type ChangeEventName as ab, type ClockMode as ac, type Column as ad, type ColumnMap as ae, type CommandContractMethodSpec as af, type CommandInputShape as ag, type CommandMethod as ah, type CommandPlan as ai, type CommandResolutionTarget as aj, type CommandResultKind as ak, type CommandSelectShape as al, type CompiledFragment as am, type ComposeSpec as an, type CondSlot as ao, type ConditionCheckInput as ap, type Connection as aq, type ContractCallSignature as ar, type ContractCardinality as as, type ContractCommandParams as at, type ContractCommandResult as au, type ContractComposeNode as av, type ContractFromRef as aw, type ContractInputArity as ax, type ContractItem as ay, type ContractKeyFieldRef as az, type WriteResult as b, type UniqueEffect as b$, type InputArity as b0, type KeyDefinitionMarker as b1, type KeySegment as b2, type KeySlot as b3, type KeyStructure as b4, type KeyedResult as b5, LIFECYCLE_CONTRACT_MARKER as b6, type LifecycleContract as b7, type LifecycleEffects as b8, type LiteralParam as b9, type PutOptions as bA, type QueryContractMethodSpec as bB, type QueryEnvelopeResult as bC, type QueryKeyOf as bD, type QueryMethod as bE, type QueryResult as bF, type RangeConditionSpec as bG, type ReadEnvelope as bH, type ReadOperationType as bI, type ReadRouteDescriptor as bJ, type ReadRouteOptions as bK, type ReadRouteResult as bL, type RecordedCompose as bM, type RelationBuilder as bN, type RelationSelect as bO, type RelationSpec as bP, type RequiresEffect as bQ, type Resolution as bR, SPEC_VERSION as bS, type SegmentSpec as bT, type SelectBuilder as bU, type SelectOf as bV, type StartingPosition as bW, type StreamViewType as bX, type StringParam as bY, TransactionContext as bZ, type TransactionItemType as b_, type ManifestEntity as ba, type ManifestField as bb, type ManifestFieldType as bc, type ManifestGsi as bd, type ManifestKey as be, type ManifestRelation as bf, type ManifestTable as bg, type ModelRef as bh, type MutateMode as bi, type MutateOptions as bj, type MutateParallelResult as bk, type MutateTransactionResult as bl, type MutationBody as bm, type MutationDescriptorMap as bn, type MutationFragment as bo, type MutationInputProxy as bp, type MutationInputRef as bq, type MutationIntent as br, type NumberParam as bs, type OperationKind as bt, type OperationSpec as bu, type ParallelOpResult as bv, type ParamKind as bw, type ParamSpec as bx, type ParamStructure as by, type PlannedCommandMethod as bz, type DeleteInput as c, type Updatable as c0, type UpdateOptions as c1, type WhenSpec as c2, type WriteDescriptor as c3, type WriteEnvelope as c4, type WriteLifecyclePhase as c5, type WriteOperationType as c6, type WriteRecorder as c7, type WriteResultProjection as c8, attachModelClass as c9, isContractComposeNode as cA, isContractFromRef as cB, isContractKeyFieldRef as cC, isContractKeyRef as cD, isContractParamRef as cE, isEntityWritesDefinition as cF, isKeySegment as cG, isLifecycleContract as cH, isMutationFragment as cI, isMutationInputRef as cJ, isParam as cK, isPlannedCommandMethod as cL, isQueryModelContract as cM, k as cN, key as cO, lifecyclePhaseForIntent as cP, mintContractKeyFieldRef as cQ, mintContractParamRef as cR, mutation as cS, param as cT, publicCommandModel as cU, publicQueryModel as cV, query as cW, resolveLifecycle as cX, wholeKeysSentinel as cY, buildDeleteInput as ca, buildPutInput as cb, buildUpdateInput as cc, compileFragment as cd, compileMutationPlan as ce, compileSingleFragmentPlan as cf, cond as cg, contractOfMethodSpec as ch, definePlan as ci, entityWrites as cj, executeBatchGet as ck, executeBatchWrite as cl, executeCommandMethod as cm, executeDelete as cn, executeKeyedBatchGet as co, executePut as cp, executeQueryMethod as cq, executeRangeFanout as cr, executeTransaction as cs, executeUpdate as ct, from as cu, getEntityWrites as cv, gsi as cw, isColumn as cx, isCommandModelContract as cy, isCommandPlan as cz, type BatchWriteExecItem as d, DDBModel as e, type PrimaryKeyOf as f, type ExecutionPlanSpec as g, type SegmentedKey as h, type SelectBuilderSpec as i, type TransactionSpec as j, type Manifest as k, type ExecutionPlan as l, type ResolvedKey as m, type CdcEmulatorOptions as n, type ChangeHandler as o, type Unsubscribe as p, type ConcurrentRecomputeRef as q, type EventLog as r, type ReplayOptions as s, type ShardId as t, type TransactionItemSpec as u, type Param as v, type ParamDescriptor as w, type DefinitionMap as x, type WriteDefinitionOptions as y, type PartialQueryKeyOf as z };