graphddb 0.1.0

package/dist/index.js

@@ -0,0 +1,2887 @@
+import {
+  EDGE_WRITES_MARKER,
+  ENTITY_WRITES_MARKER,
+  LIFECYCLE_CONTRACT_MARKER,
+  MARKER_ROW_ENTITY,
+  OLD_VALUE_NAMESPACE,
+  RELATION_TRAVERSAL_CONCURRENCY,
+  SPEC_VERSION,
+  assertBundleSerializable,
+  assertContractBoundaries,
+  assertContractN1Safe,
+  assertJsonSerializable,
+  assertSupportedCondition,
+  buildBridgeBundle,
+  buildContexts,
+  buildContracts,
+  buildManifest,
+  buildOperations,
+  buildProject,
+  buildQuerySpec,
+  buildRelation,
+  buildRelationExecutionPlan,
+  buildTransactionSpec,
+  buildTransactions,
+  collectContractBoundaryViolations,
+  collectContractN1Violations,
+  command,
+  compileFragment,
+  compileMutationPlan,
+  compileSingleFragmentPlan,
+  contractOfMethodSpec,
+  definePlan,
+  defineTransaction,
+  defineTransactions,
+  deriveCompositionPlan,
+  deriveEdgeWriteItems,
+  deriveEdgeWriteItemsFor,
+  deriveModelEdgeWriteItems,
+  detectRelationFields,
+  edgeWrites,
+  entityWrites,
+  from,
+  getEdgeWrites,
+  getEntityWrites,
+  getImplicitKeyFields,
+  isCommandBatchMode,
+  isCommandModelContract,
+  isCommandPlan,
+  isContractComposeNode,
+  isContractFromRef,
+  isContractKeyFieldRef,
+  isContractKeyRef,
+  isContractParamRef,
+  isEdgeWritesDefinition,
+  isEntityWritesDefinition,
+  isLifecycleContract,
+  isMutationFragment,
+  isMutationInputRef,
+  isParam,
+  isPlannedCommandMethod,
+  isQueryModelContract,
+  isRecordingContractMethod,
+  isSelectBuilder,
+  isTransactionRef,
+  lifecyclePhaseForIntent,
+  mapWithConcurrency,
+  mintContractKeyFieldRef,
+  mintContractParamRef,
+  mutation,
+  normalizeSelectSpec,
+  normalizeTopLevelSelect,
+  param,
+  point,
+  publicCommandModel,
+  publicQueryModel,
+  query,
+  range,
+  recordContractOp,
+  resolveLifecycle,
+  stageOfResultPath,
+  when,
+  wholeKeysSentinel
+} from "./chunk-6LEHSX45.js";
+import {
+  CdcEmulator,
+  createCdcEmulator
+} from "./chunk-UNRQ5YJT.js";
+import {
+  BATCH_GET_MAX_KEYS,
+  BATCH_WRITE_MAX_ITEMS,
+  ChangeCaptureRegistry,
+  ClientManager,
+  DynamoExecutor,
+  Linter,
+  MAX_TRANSACT_ITEMS,
+  MetadataRegistry,
+  TableMapping,
+  TransactionContext,
+  attachHiddenKey,
+  attachModelClass,
+  buildConditionExpression,
+  buildDeleteInput,
+  buildPutInput,
+  buildUpdateExpression,
+  buildUpdateInput,
+  captureWrite,
+  collapseSameKeyItems,
+  commitTransaction,
+  createColumnMap,
+  createDefaultLinter,
+  execItemKeySignature,
+  executeDelete,
+  executePut,
+  executeTransaction,
+  executeUpdate,
+  gsi,
+  gsiAmbiguityRule,
+  isColumn,
+  isKeySegment,
+  k,
+  key,
+  missingGsiRule,
+  noScanRule,
+  relationDepthRule,
+  requireLimitRule,
+  resolveKey,
+  resolveModelClass,
+  resolveSegmentedKey,
+  serializeFieldValue
+} from "./chunk-347U24SB.js";
+
+// src/metadata/prefix.ts
+function derivePrefix(customPrefix, className) {
+  if (customPrefix != null) {
+    return `${customPrefix}#`;
+  }
+  if (!className) {
+    throw new Error(
+      'Cannot derive PK prefix: class name is undefined. Provide an explicit prefix via @model({ prefix: "..." }).'
+    );
+  }
+  const base = className.endsWith("Model") ? className.slice(0, -"Model".length) : className;
+  return `${base}#`;
+}
+
+// src/metadata/validation.ts
+function isSubsetOf(a, b) {
+  const setB = new Set(b);
+  return a.length > 0 && a.every((f) => setB.has(f));
+}
+function validateGsiAmbiguity(primaryKey, gsiDefinitions) {
+  const patterns = [];
+  if (primaryKey) {
+    patterns.push({
+      label: "primaryKey",
+      fieldNames: primaryKey.inputFieldNames
+    });
+  }
+  for (const gsi2 of gsiDefinitions) {
+    patterns.push({ label: gsi2.indexName, fieldNames: gsi2.inputFieldNames });
+  }
+  for (let i = 0; i < patterns.length; i++) {
+    for (let j = i + 1; j < patterns.length; j++) {
+      const a = patterns[i];
+      const b = patterns[j];
+      if (isSubsetOf(a.fieldNames, b.fieldNames) || isSubsetOf(b.fieldNames, a.fieldNames)) {
+        const smaller = a.fieldNames.length <= b.fieldNames.length ? a : b;
+        throw new Error(
+          `Ambiguous GSI resolution: field set [${smaller.fieldNames.join(", ")}] matches both '${a.label}' and '${b.label}'. Each access pattern must have a unique field combination.`
+        );
+      }
+    }
+  }
+}
+
+// src/decorators/collector.ts
+var pendingFields = [];
+var pendingEmbedded = [];
+var pendingRelations = [];
+function collectField(field2) {
+  pendingFields.push(field2);
+}
+function collectEmbedded(embedded2) {
+  pendingEmbedded.push(embedded2);
+}
+function collectRelation(relation) {
+  pendingRelations.push(relation);
+}
+function drainFields() {
+  const result = pendingFields;
+  pendingFields = [];
+  return result;
+}
+function drainEmbedded() {
+  const result = pendingEmbedded;
+  pendingEmbedded = [];
+  return result;
+}
+function drainRelations() {
+  const result = pendingRelations;
+  pendingRelations = [];
+  return result;
+}
+
+// src/decorators/model.ts
+function model(options) {
+  return function(target, context) {
+    const fields = drainFields();
+    const embeddedFields = drainEmbedded();
+    const relations = drainRelations();
+    const prefix = derivePrefix(options.prefix, context.name);
+    MetadataRegistry.register(target, {
+      tableName: options.table,
+      prefix,
+      fields,
+      primaryKey: null,
+      gsiDefinitions: [],
+      relations,
+      embeddedFields
+    });
+  };
+}
+
+// src/decorators/field.ts
+function field(dynamoType, options) {
+  return function(_value, context) {
+    collectField({
+      propertyName: String(context.name),
+      dynamoType,
+      options
+    });
+  };
+}
+function createFieldDecorator(dynamoType, defaultOptions) {
+  function fieldDecorator(optionsOrContext, context) {
+    if (context) {
+      collectField({
+        propertyName: String(context.name),
+        dynamoType,
+        options: defaultOptions
+      });
+      return;
+    }
+    const options = { ...defaultOptions, ...optionsOrContext };
+    return (_value, ctx) => {
+      collectField({
+        propertyName: String(ctx.name),
+        dynamoType,
+        options: Object.keys(options).length > 0 ? options : void 0
+      });
+    };
+  }
+  return fieldDecorator;
+}
+function literal(...values) {
+  if (values.length === 0) {
+    throw new Error(
+      "@literal(...) requires at least one allowed value (e.g. @literal('active', 'disabled'))."
+    );
+  }
+  return (_value, context) => {
+    collectField({
+      propertyName: String(context.name),
+      dynamoType: "S",
+      literals: [...values]
+    });
+  };
+}
+var string = createFieldDecorator("S");
+var number = createFieldDecorator("N");
+var boolean = createFieldDecorator("BOOL");
+var datetime = createFieldDecorator("S", { format: "datetime" });
+var binary = createFieldDecorator("B");
+var stringSet = createFieldDecorator("SS");
+var numberSet = createFieldDecorator("NS");
+var list = createFieldDecorator("L");
+var map = createFieldDecorator("M");
+
+// src/decorators/embedded.ts
+function embedded(modelFactory) {
+  return function(_value, context) {
+    collectEmbedded({
+      propertyName: String(context.name),
+      modelFactory
+    });
+  };
+}
+
+// src/decorators/relation.ts
+var RESERVED_RELATION_PROPERTY_NAMES = /* @__PURE__ */ new Set([
+  "items"
+]);
+function assertRelationPropertyNameAllowed(propertyName) {
+  if (RESERVED_RELATION_PROPERTY_NAMES.has(propertyName)) {
+    throw new Error(
+      `Relation property name '${propertyName}' is reserved: it collides with the relation result-path grammar token '${propertyName}', which the planner and runtimes use to mark a hasMany connection (a relation writes to '$.<prop>.items'). A relation named '${propertyName}' would be mis-staged at runtime. Rename the relation property (reserved names: ${[...RESERVED_RELATION_PROPERTY_NAMES].map((n) => `'${n}'`).join(", ")}).`
+    );
+  }
+}
+function hasMany(targetFactory, keyBinding, options) {
+  return function(_value, context) {
+    const propertyName = String(context.name);
+    assertRelationPropertyNameAllowed(propertyName);
+    collectRelation({
+      type: "hasMany",
+      propertyName,
+      targetFactory,
+      keyBinding,
+      options
+    });
+  };
+}
+function belongsTo(targetFactory, keyBinding) {
+  return function(_value, context) {
+    const propertyName = String(context.name);
+    assertRelationPropertyNameAllowed(propertyName);
+    collectRelation({
+      type: "belongsTo",
+      propertyName,
+      targetFactory,
+      keyBinding
+    });
+  };
+}
+function hasOne(targetFactory, keyBinding) {
+  return function(_value, context) {
+    const propertyName = String(context.name);
+    assertRelationPropertyNameAllowed(propertyName);
+    collectRelation({
+      type: "hasOne",
+      propertyName,
+      targetFactory,
+      keyBinding
+    });
+  };
+}
+
+// src/planner/projection.ts
+function buildProjection(select, additionalFields) {
+  const paths = [];
+  const names = {};
+  let nameCounter = 0;
+  function addPath(segments) {
+    const aliased = segments.map((seg) => {
+      const alias = `#p${nameCounter++}`;
+      names[alias] = seg;
+      return alias;
+    });
+    paths.push(aliased.join("."));
+  }
+  function traverse(selectObj, parentSegments) {
+    for (const [fieldName, value] of Object.entries(selectObj)) {
+      if (value === true) {
+        addPath([...parentSegments, fieldName]);
+      } else if (typeof value === "object" && value !== null) {
+        if ("select" in value || isSelectBuilder(value)) {
+          continue;
+        }
+        traverse(value, [...parentSegments, fieldName]);
+      }
+    }
+  }
+  traverse(select, []);
+  if (additionalFields) {
+    for (const fieldName of additionalFields) {
+      addPath([fieldName]);
+    }
+  }
+  if (paths.length === 0) {
+    return void 0;
+  }
+  return {
+    projectionExpression: paths.join(", "),
+    expressionAttributeNames: names
+  };
+}
+
+// src/select/cond.ts
+var RAW_COND = /* @__PURE__ */ Symbol.for("graphddb.rawCond");
+function isRawCondition(value) {
+  return typeof value === "object" && value !== null && value[RAW_COND] === true;
+}
+function cond(template, ...parts) {
+  return {
+    [RAW_COND]: true,
+    template,
+    parts
+  };
+}
+function compileRawCondition(raw, allocName, allocValue) {
+  let out = raw.template[0];
+  for (let i = 0; i < raw.parts.length; i++) {
+    const part = raw.parts[i];
+    if (isColumn(part)) {
+      out += allocName(part.name);
+    } else {
+      out += allocValue(part);
+    }
+    out += raw.template[i + 1];
+  }
+  return out;
+}
+
+// src/expression/filter-expression.ts
+var LOGICAL_KEYS = /* @__PURE__ */ new Set(["and", "or", "not"]);
+var OPERATOR_KEYS = /* @__PURE__ */ new Set([
+  "eq",
+  "ne",
+  "gt",
+  "ge",
+  "lt",
+  "le",
+  "between",
+  "in",
+  "beginsWith",
+  "contains",
+  "notContains",
+  "attributeExists",
+  "attributeType",
+  "size"
+]);
+function nameAlias(ctx, column) {
+  for (const [alias2, col] of Object.entries(ctx.names)) {
+    if (col === column) return alias2;
+  }
+  const alias = `#f${ctx.nameCounter.n++}`;
+  ctx.names[alias] = column;
+  return alias;
+}
+function valueAlias(ctx, field2, raw) {
+  const alias = `:vf${ctx.valueCounter.n++}`;
+  const fieldMeta = ctx.fieldMap.get(field2);
+  ctx.values[alias] = fieldMeta ? serializeFieldValue(raw, fieldMeta) : raw;
+  return alias;
+}
+function compileField(ctx, field2, condition) {
+  const nAlias = nameAlias(ctx, field2);
+  if (!isOperatorObject(condition)) {
+    const vAlias = valueAlias(ctx, field2, condition);
+    return `${nAlias} = ${vAlias}`;
+  }
+  const ops = condition;
+  const clauses = [];
+  for (const [op, value] of Object.entries(ops)) {
+    switch (op) {
+      case "eq":
+        clauses.push(`${nAlias} = ${valueAlias(ctx, field2, value)}`);
+        break;
+      case "ne":
+        clauses.push(`${nAlias} <> ${valueAlias(ctx, field2, value)}`);
+        break;
+      case "gt":
+        clauses.push(`${nAlias} > ${valueAlias(ctx, field2, value)}`);
+        break;
+      case "ge":
+        clauses.push(`${nAlias} >= ${valueAlias(ctx, field2, value)}`);
+        break;
+      case "lt":
+        clauses.push(`${nAlias} < ${valueAlias(ctx, field2, value)}`);
+        break;
+      case "le":
+        clauses.push(`${nAlias} <= ${valueAlias(ctx, field2, value)}`);
+        break;
+      case "between": {
+        const [lo, hi] = value;
+        clauses.push(
+          `${nAlias} BETWEEN ${valueAlias(ctx, field2, lo)} AND ${valueAlias(ctx, field2, hi)}`
+        );
+        break;
+      }
+      case "in": {
+        const arr = value;
+        const aliases = arr.map((v) => valueAlias(ctx, field2, v));
+        clauses.push(`${nAlias} IN (${aliases.join(", ")})`);
+        break;
+      }
+      case "beginsWith":
+        clauses.push(`begins_with(${nAlias}, ${valueAlias(ctx, field2, value)})`);
+        break;
+      case "contains":
+        clauses.push(`contains(${nAlias}, ${valueAlias(ctx, field2, value)})`);
+        break;
+      case "notContains":
+        clauses.push(
+          `NOT contains(${nAlias}, ${valueAlias(ctx, field2, value)})`
+        );
+        break;
+      case "attributeExists":
+        clauses.push(
+          value === false ? `attribute_not_exists(${nAlias})` : `attribute_exists(${nAlias})`
+        );
+        break;
+      case "attributeType":
+        clauses.push(
+          `attribute_type(${nAlias}, ${valueAlias(ctx, field2, value)})`
+        );
+        break;
+      case "size":
+        clauses.push(`size(${nAlias}) = ${valueAlias(ctx, field2, value)}`);
+        break;
+      default:
+        throw new Error(`Unknown filter operator '${op}' on field '${field2}'`);
+    }
+  }
+  return joinAnd(clauses);
+}
+function isOperatorObject(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value) || value instanceof Date || value instanceof Uint8Array || value instanceof Set) {
+    return false;
+  }
+  const keys = Object.keys(value);
+  if (keys.length === 0) return false;
+  return keys.every((k2) => OPERATOR_KEYS.has(k2));
+}
+function joinAnd(clauses) {
+  if (clauses.length === 1) return clauses[0];
+  return clauses.map((c) => wrap(c)).join(" AND ");
+}
+function wrap(expr) {
+  if (isAlreadyWrapped(expr)) return expr;
+  if (expr.includes(" AND ") || expr.includes(" OR ")) {
+    return `(${expr})`;
+  }
+  return expr;
+}
+function isAlreadyWrapped(expr) {
+  if (!expr.startsWith("(") || !expr.endsWith(")")) return false;
+  let depth = 0;
+  for (let i = 0; i < expr.length; i++) {
+    if (expr[i] === "(") depth++;
+    else if (expr[i] === ")") {
+      depth--;
+      if (depth === 0 && i < expr.length - 1) return false;
+    }
+  }
+  return depth === 0;
+}
+function compileRaw(ctx, raw) {
+  return compileRawCondition(
+    raw,
+    (column) => nameAlias(ctx, column),
+    (value) => {
+      const alias = `:vf${ctx.valueCounter.n++}`;
+      ctx.values[alias] = value;
+      return alias;
+    }
+  );
+}
+function compileNode(ctx, node) {
+  if (isRawCondition(node)) {
+    return compileRaw(ctx, node);
+  }
+  const clauses = [];
+  for (const [key2, value] of Object.entries(node)) {
+    if (value === void 0) continue;
+    if (LOGICAL_KEYS.has(key2)) {
+      if (key2 === "and" || key2 === "or") {
+        const parts = value.map((sub) => compileNode(ctx, sub)).filter((s) => s.length > 0);
+        if (parts.length === 0) continue;
+        if (parts.length === 1) {
+          clauses.push(parts[0]);
+        } else {
+          const sep = key2 === "and" ? " AND " : " OR ";
+          const joined = parts.map((p) => wrap(p)).join(sep);
+          clauses.push(`(${joined})`);
+        }
+      } else {
+        const inner = compileNode(ctx, value);
+        if (inner.length > 0) clauses.push(`NOT ${wrap(inner)}`);
+      }
+      continue;
+    }
+    const clause = compileField(ctx, key2, value);
+    if (clause.length > 0) clauses.push(clause);
+  }
+  return joinAnd(clauses);
+}
+function compileFilterExpression(filter, metadata) {
+  if (!filter || Object.keys(filter).length === 0) {
+    return void 0;
+  }
+  const ctx = {
+    names: {},
+    values: {},
+    fieldMap: new Map(metadata.fields.map((f) => [f.propertyName, f])),
+    nameCounter: { n: 0 },
+    valueCounter: { n: 0 }
+  };
+  const expression = compileNode(ctx, filter);
+  if (expression.length === 0) {
+    return void 0;
+  }
+  return {
+    filterExpression: expression,
+    expressionAttributeNames: ctx.names,
+    expressionAttributeValues: ctx.values
+  };
+}
+function evaluateFilter(item, filter) {
+  for (const [key2, value] of Object.entries(filter)) {
+    if (value === void 0) continue;
+    if (key2 === "and") {
+      if (!value.every((s) => evaluateFilter(item, s)))
+        return false;
+      continue;
+    }
+    if (key2 === "or") {
+      if (!value.some((s) => evaluateFilter(item, s)))
+        return false;
+      continue;
+    }
+    if (key2 === "not") {
+      if (evaluateFilter(item, value)) return false;
+      continue;
+    }
+    if (!evaluateFieldCondition(item[key2], item, key2, value)) {
+      return false;
+    }
+  }
+  return true;
+}
+function cmp(a, b) {
+  if (a instanceof Date && b instanceof Date) {
+    return a.getTime() - b.getTime();
+  }
+  if (typeof a === "number" && typeof b === "number") return a - b;
+  if (typeof a === "string" && typeof b === "string")
+    return a < b ? -1 : a > b ? 1 : 0;
+  if (a === b) return 0;
+  return a < b ? -1 : 1;
+}
+function eq(a, b) {
+  if (a instanceof Date && b instanceof Date) return a.getTime() === b.getTime();
+  return a === b;
+}
+function evaluateFieldCondition(actual, item, field2, condition) {
+  if (!isOperatorObject(condition)) {
+    return eq(actual, condition);
+  }
+  const ops = condition;
+  for (const [op, value] of Object.entries(ops)) {
+    switch (op) {
+      case "eq":
+        if (!eq(actual, value)) return false;
+        break;
+      case "ne":
+        if (eq(actual, value)) return false;
+        break;
+      case "gt":
+        if (!(cmp(actual, value) > 0)) return false;
+        break;
+      case "ge":
+        if (!(cmp(actual, value) >= 0)) return false;
+        break;
+      case "lt":
+        if (!(cmp(actual, value) < 0)) return false;
+        break;
+      case "le":
+        if (!(cmp(actual, value) <= 0)) return false;
+        break;
+      case "between": {
+        const [lo, hi] = value;
+        if (!(cmp(actual, lo) >= 0 && cmp(actual, hi) <= 0)) return false;
+        break;
+      }
+      case "in":
+        if (!value.some((v) => eq(actual, v))) return false;
+        break;
+      case "beginsWith":
+        if (typeof actual !== "string" || !actual.startsWith(value))
+          return false;
+        break;
+      case "contains":
+        if (typeof actual !== "string" || !actual.includes(value))
+          return false;
+        break;
+      case "notContains":
+        if (typeof actual === "string" && actual.includes(value))
+          return false;
+        break;
+      case "attributeExists": {
+        const exists = field2 in item && actual !== void 0 && actual !== null;
+        if (value === false ? exists : !exists) return false;
+        break;
+      }
+      case "attributeType":
+        break;
+      case "size": {
+        const len = typeof actual === "string" || Array.isArray(actual) ? actual.length : void 0;
+        if (len !== value) return false;
+        break;
+      }
+      default:
+        throw new Error(`Unknown filter operator '${op}' on field '${field2}'`);
+    }
+  }
+  return true;
+}
+
+// src/planner/planner.ts
+function plan(metadata, input) {
+  const queryFields = Object.keys(input.key);
+  const resolved = resolveKey(queryFields, metadata);
+  if (input.consistentRead && resolved.type === "gsi") {
+    throw new Error(
+      "consistentRead is not supported for GSI queries. Use a primary key query instead."
+    );
+  }
+  const tableName = TableMapping.resolve(metadata.tableName);
+  const built = buildKeyCondition(metadata, resolved, input.key);
+  const keyCondition = built.keyCondition;
+  const additionalProjectionFields = input.updatable ? Array.from(
+    /* @__PURE__ */ new Set([...input.additionalProjectionFields ?? [], "PK", "SK"])
+  ) : input.additionalProjectionFields;
+  const projection = buildProjection(input.select, additionalProjectionFields);
+  const compiledFilter = compileFilterExpression(input.filter, metadata);
+  const isGetItem = resolved.type === "pk" && !resolved.partial && built.skValue !== void 0 && // GetItem does not support FilterExpression — fall back to Query when a
+  // server-side filter is requested so the condition can be applied.
+  !compiledFilter;
+  const projectionFields = projection ? {
+    projectionExpression: projection.projectionExpression,
+    expressionAttributeNames: projection.expressionAttributeNames
+  } : {};
+  const filterFields = compiledFilter ? {
+    filterExpression: compiledFilter.filterExpression,
+    filterExpressionAttributeNames: compiledFilter.expressionAttributeNames,
+    filterExpressionAttributeValues: compiledFilter.expressionAttributeValues
+  } : {};
+  const consistentRead = input.consistentRead && resolved.type === "pk" ? { consistentRead: true } : {};
+  let op;
+  if (isGetItem) {
+    op = {
+      type: "GetItem",
+      tableName,
+      keyCondition,
+      ...projectionFields,
+      ...consistentRead
+    };
+  } else {
+    const queryOp = {
+      type: "Query",
+      tableName,
+      keyCondition,
+      scanIndexForward: (input.order ?? "ASC") === "ASC",
+      ...projectionFields,
+      ...filterFields,
+      ...consistentRead
+    };
+    if (resolved.type === "gsi") {
+      queryOp.indexName = resolved.indexName;
+    }
+    if (built.rangeCondition) {
+      queryOp.rangeCondition = built.rangeCondition;
+    }
+    if (input.limit != null) {
+      queryOp.limit = input.limit;
+    }
+    if (input.after) {
+      queryOp.exclusiveStartKey = input.after;
+    }
+    op = queryOp;
+  }
+  return { operations: [op] };
+}
+function buildKeyCondition(metadata, resolved, queryKey) {
+  if (resolved.type === "pk") {
+    if (!metadata.primaryKey) throw new Error("Primary key not defined");
+    return buildFromSegments(
+      metadata.primaryKey.segmented,
+      metadata.primaryKey.inputFieldNames,
+      queryKey,
+      "PK",
+      "SK"
+    );
+  }
+  const gsiDef = metadata.gsiDefinitions.find(
+    (g) => g.indexName === resolved.indexName
+  );
+  if (!gsiDef) throw new Error(`GSI '${resolved.indexName}' not found`);
+  return buildFromSegments(
+    gsiDef.segmented,
+    gsiDef.inputFieldNames,
+    queryKey,
+    `${gsiDef.indexName}PK`,
+    `${gsiDef.indexName}SK`
+  );
+}
+function buildFromSegments(segmented, inputFieldNames, queryKey, pkAttr, skAttr) {
+  const keyInput = {};
+  for (const fieldName of inputFieldNames) {
+    keyInput[fieldName] = queryKey[fieldName];
+  }
+  const { pk, sk, skTruncated } = resolveSegmentedKey(segmented, keyInput);
+  const keyCondition = { [pkAttr]: pk };
+  if (sk === void 0) {
+    return { keyCondition };
+  }
+  if (skTruncated) {
+    return {
+      keyCondition,
+      rangeCondition: { operator: "begins_with", key: skAttr, value: sk }
+    };
+  }
+  keyCondition[skAttr] = sk;
+  return { keyCondition, skValue: sk };
+}
+
+// src/executor/executor.ts
+async function execute(operation) {
+  return ClientManager.getExecutor().execute(operation);
+}
+
+// src/hydrator/hydrator.ts
+function hydrate(rawItems, select, metadata, updatable = false) {
+  return rawItems.map((item) => hydrateItem(item, select, metadata, updatable));
+}
+function hydrateItem(raw, select, metadata, updatable = false) {
+  const fieldMap = new Map(
+    metadata.fields.map((f) => [f.propertyName, f])
+  );
+  const embeddedMap = new Map(
+    metadata.embeddedFields.map((e) => [e.propertyName, e])
+  );
+  const result = {};
+  for (const [fieldName, selectValue] of Object.entries(select)) {
+    if (selectValue === true) {
+      const value = raw[fieldName];
+      if (value !== void 0) {
+        const fieldMeta = fieldMap.get(fieldName);
+        result[fieldName] = deserializeValue(value, fieldMeta);
+      }
+    } else if (typeof selectValue === "object" && selectValue !== null) {
+      if ("select" in selectValue || isSelectBuilder(selectValue)) {
+        continue;
+      }
+      const rawEmb = raw[fieldName];
+      if (rawEmb && typeof rawEmb === "object") {
+        result[fieldName] = hydrateEmbedded(
+          rawEmb,
+          selectValue,
+          metadata,
+          fieldName
+        );
+      }
+    }
+  }
+  if (updatable) {
+    attachHiddenKey(result, raw);
+  }
+  return result;
+}
+function hydrateEmbedded(raw, select, _metadata, _fieldName) {
+  const result = {};
+  for (const [key2, selectValue] of Object.entries(select)) {
+    if (selectValue === true) {
+      if (raw[key2] !== void 0) {
+        result[key2] = raw[key2];
+      }
+    } else if (typeof selectValue === "object" && selectValue !== null && !("select" in selectValue)) {
+      const nested = raw[key2];
+      if (nested && typeof nested === "object") {
+        result[key2] = hydrateEmbedded(
+          nested,
+          selectValue,
+          _metadata,
+          key2
+        );
+      }
+    }
+  }
+  return result;
+}
+function deserializeValue(value, fieldMeta) {
+  if (!fieldMeta) return value;
+  if (fieldMeta.options?.deserialize) {
+    return fieldMeta.options.deserialize(value);
+  }
+  if (fieldMeta.options?.format === "datetime" && typeof value === "string") {
+    return new Date(value);
+  }
+  if (fieldMeta.options?.format === "date" && typeof value === "string") {
+    return /* @__PURE__ */ new Date(value + "T00:00:00.000Z");
+  }
+  return value;
+}
+
+// src/pagination/cursor.ts
+function encodeCursor(lastEvaluatedKey) {
+  const json = JSON.stringify(lastEvaluatedKey);
+  const bytes = new TextEncoder().encode(json);
+  let binary2 = "";
+  for (const b of bytes) {
+    binary2 += String.fromCharCode(b);
+  }
+  return btoa(binary2).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function decodeCursor(cursor) {
+  let base64 = cursor.replace(/-/g, "+").replace(/_/g, "/");
+  while (base64.length % 4 !== 0) {
+    base64 += "=";
+  }
+  const binary2 = atob(base64);
+  const bytes = new Uint8Array(binary2.length);
+  for (let i = 0; i < binary2.length; i++) {
+    bytes[i] = binary2.charCodeAt(i);
+  }
+  const json = new TextDecoder().decode(bytes);
+  return JSON.parse(json);
+}
+
+// src/operations/list.ts
+async function executeListInternal(modelClass, key2, options) {
+  const metadata = MetadataRegistry.get(modelClass);
+  const normalized = normalizeTopLevelSelect(options.select);
+  const select = normalized.select;
+  const filter = options.filter ?? normalized.filter;
+  const after = options.after ?? normalized.after;
+  const limit = options.limit ?? normalized.limit;
+  const order = options.order ?? normalized.order;
+  const exclusiveStartKey = after ? decodeCursor(after) : void 0;
+  const implicitKeys = getImplicitKeyFields(select, metadata);
+  const executionPlan = plan(metadata, {
+    key: key2,
+    select,
+    limit,
+    after: exclusiveStartKey,
+    order,
+    filter,
+    additionalProjectionFields: implicitKeys.length > 0 ? implicitKeys : void 0,
+    updatable: options.updatable ?? false
+  });
+  const operation = executionPlan.operations[0];
+  const result = await execute(operation);
+  const rawItems = result.items;
+  const hydrated = hydrate(rawItems, select, metadata, options.updatable ?? false);
+  const cursor = result.lastEvaluatedKey ? encodeCursor(result.lastEvaluatedKey) : null;
+  return { items: hydrated, rawItems, cursor };
+}
+async function executeList(modelClass, key2, options) {
+  const { items, cursor } = await executeListInternal(modelClass, key2, options);
+  return { items, cursor };
+}
+
+// src/planner/relation-planner.ts
+function buildRelationQueryKey(rel, rawParentItem) {
+  const queryKey = {};
+  for (const [targetField, sourceField] of Object.entries(rel.keyBinding)) {
+    queryKey[targetField] = rawParentItem[sourceField];
+  }
+  return queryKey;
+}
+function serializeQueryKey(queryKey) {
+  const entries = Object.entries(queryKey).sort(([a], [b]) => a.localeCompare(b));
+  return JSON.stringify(entries);
+}
+function planGetItemForQueryKey(metadata, queryKey, select, additionalProjectionFields) {
+  const executionPlan = plan(metadata, {
+    key: queryKey,
+    select,
+    additionalProjectionFields
+  });
+  const operation = executionPlan.operations[0];
+  if (operation.type !== "GetItem") {
+    throw new Error(
+      `Relation target requires GetItem access pattern, got ${operation.type}`
+    );
+  }
+  return operation;
+}
+function planBatchGetForQueryKeys(metadata, queryKeys, select, additionalProjectionFields) {
+  if (queryKeys.length === 0) {
+    return [];
+  }
+  const keyFields = [
+    ...new Set(queryKeys.flatMap((queryKey) => Object.keys(queryKey)))
+  ].filter((field2) => !(field2 in select && select[field2] === true));
+  const projectionFields = [
+    .../* @__PURE__ */ new Set([
+      ...(additionalProjectionFields ?? []).filter(
+        (field2) => !(field2 in select && select[field2] === true)
+      ),
+      ...keyFields
+    ])
+  ];
+  const samplePlan = planGetItemForQueryKey(
+    metadata,
+    queryKeys[0],
+    select,
+    projectionFields.length > 0 ? projectionFields : void 0
+  );
+  const uniqueKeys = dedupeDynamoKeys(
+    queryKeys.map(
+      (queryKey) => planGetItemForQueryKey(
+        metadata,
+        queryKey,
+        select,
+        projectionFields.length > 0 ? projectionFields : void 0
+      ).keyCondition
+    )
+  );
+  const operations = [];
+  for (let i = 0; i < uniqueKeys.length; i += BATCH_GET_MAX_KEYS) {
+    operations.push({
+      type: "BatchGetItem",
+      tableName: samplePlan.tableName,
+      keys: uniqueKeys.slice(i, i + BATCH_GET_MAX_KEYS),
+      ...samplePlan.projectionExpression ? { projectionExpression: samplePlan.projectionExpression } : {},
+      ...samplePlan.expressionAttributeNames ? { expressionAttributeNames: samplePlan.expressionAttributeNames } : {},
+      ...samplePlan.consistentRead ? { consistentRead: true } : {}
+    });
+  }
+  return operations;
+}
+function dedupeDynamoKeys(keys) {
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
+  for (const key2 of keys) {
+    const serialized = JSON.stringify(
+      Object.entries(key2).sort(([a], [b]) => a.localeCompare(b))
+    );
+    if (seen.has(serialized)) continue;
+    seen.add(serialized);
+    result.push(key2);
+  }
+  return result;
+}
+function planRelationOperations(metadata, select, context = { estimatedParentCount: 1 }) {
+  const operations = [];
+  const relations = detectRelationFields(select, metadata);
+  for (const rel of relations) {
+    const selectSpec = normalizeSelectSpec(select[rel.propertyName]);
+    const targetClass = rel.targetFactory();
+    const targetMeta = MetadataRegistry.get(targetClass);
+    if (rel.type === "hasMany") {
+      const limit = selectSpec.limit ?? rel.options?.limit?.default ?? 20;
+      const tableName = TableMapping.resolve(targetMeta.tableName);
+      const listPlan = plan(targetMeta, {
+        key: buildPlaceholderHasManyKey(rel, targetMeta),
+        select: selectSpec.select,
+        limit
+      });
+      operations.push(...listPlan.operations);
+      operations.push(
+        ...planRelationOperations(targetMeta, selectSpec.select, {
+          estimatedParentCount: limit
+        })
+      );
+      continue;
+    }
+    const estimatedCount = context.estimatedParentCount ?? 1;
+    operations.push(
+      ...planBatchGetForExplain(targetMeta, selectSpec.select, estimatedCount)
+    );
+    operations.push(
+      ...planRelationOperations(targetMeta, selectSpec.select, {
+        estimatedParentCount: 1
+      })
+    );
+  }
+  return operations;
+}
+function buildPlaceholderHasManyKey(rel, targetMeta) {
+  const queryKey = {};
+  for (const targetField of Object.keys(rel.keyBinding)) {
+    queryKey[targetField] = `__${targetField}__`;
+  }
+  if (targetMeta.primaryKey) {
+    for (const fieldName of targetMeta.primaryKey.inputFieldNames) {
+      if (!(fieldName in queryKey)) {
+        queryKey[fieldName] = `__${fieldName}__`;
+      }
+    }
+  }
+  return queryKey;
+}
+function planBatchGetForExplain(metadata, select, estimatedKeyCount) {
+  const placeholderKeys = Array.from(
+    { length: estimatedKeyCount },
+    (_, index) => buildExplainPlaceholderKey(metadata, index)
+  );
+  return planBatchGetForQueryKeys(metadata, placeholderKeys, select);
+}
+function buildExplainPlaceholderKey(metadata, index) {
+  const queryKey = {};
+  if (metadata.primaryKey) {
+    for (const fieldName of metadata.primaryKey.inputFieldNames) {
+      queryKey[fieldName] = `__explain_${fieldName}_${index}__`;
+    }
+  }
+  return queryKey;
+}
+
+// src/relation/traversal.ts
+function evaluateFilterClientSide(item, filter, _targetMeta) {
+  return evaluateFilter(item, filter);
+}
+function relationSpec(value) {
+  return normalizeSelectSpec(value);
+}
+function validateDepth(select, metadata, maxDepth, currentDepth = 1) {
+  for (const [fieldName, value] of Object.entries(select)) {
+    if (typeof value === "object" && value !== null && ("select" in value || isSelectBuilder(value))) {
+      const rel = metadata.relations.find((r) => r.propertyName === fieldName);
+      if (!rel) continue;
+      if (currentDepth > maxDepth) {
+        throw new Error(
+          `Relation traversal depth exceeded: '${fieldName}' at depth ${currentDepth} exceeds maxDepth ${maxDepth}. Set maxDepth: ${currentDepth} to allow this.`
+        );
+      }
+      const targetClass = rel.targetFactory();
+      const targetMeta = MetadataRegistry.get(targetClass);
+      const innerSelect = relationSpec(value).select;
+      validateDepth(innerSelect, targetMeta, maxDepth, currentDepth + 1);
+    }
+  }
+}
+function relationResultPath(parentPath, rel) {
+  const base = `${parentPath}.${rel.propertyName}`;
+  return rel.type === "hasMany" ? `${base}.items` : base;
+}
+function stageRelations(relations, parentPath, plan2) {
+  if (plan2 === void 0 || relations.length === 0) {
+    return relations.length > 0 ? { stages: [[...relations]], concurrency: RELATION_TRAVERSAL_CONCURRENCY } : { stages: [], concurrency: RELATION_TRAVERSAL_CONCURRENCY };
+  }
+  const byStage = /* @__PURE__ */ new Map();
+  const unstaged = [];
+  for (const rel of relations) {
+    const stage = stageOfResultPath(plan2, relationResultPath(parentPath, rel));
+    if (stage === void 0) {
+      unstaged.push(rel);
+      continue;
+    }
+    const bucket = byStage.get(stage);
+    if (bucket) bucket.push(rel);
+    else byStage.set(stage, [rel]);
+  }
+  const stages = [...byStage.keys()].sort((a, b) => a - b).map((s) => byStage.get(s));
+  if (unstaged.length > 0) stages.push(unstaged);
+  return { stages, concurrency: plan2.plan.concurrency };
+}
+async function runStaged(relations, parentPath, plan2, worker) {
+  const { stages, concurrency } = stageRelations(relations, parentPath, plan2);
+  for (const stage of stages) {
+    await mapWithConcurrency(stage, concurrency, (rel) => worker(rel));
+  }
+}
+function hasCompleteQueryKey(queryKey) {
+  return Object.values(queryKey).every((value) => value != null);
+}
+function matchesQueryKey(item, queryKey) {
+  return Object.entries(queryKey).every(
+    ([field2, value]) => item[field2] === value
+  );
+}
+async function fetchBelongsToHasOneBatch(rel, rawParentItems, selectSpec, targetMeta, options, currentDepth, parentPath) {
+  const results = rawParentItems.map(
+    () => null
+  );
+  const queryKeys = [];
+  const parentIndexes = [];
+  for (let i = 0; i < rawParentItems.length; i++) {
+    const queryKey = buildRelationQueryKey(rel, rawParentItems[i]);
+    if (!hasCompleteQueryKey(queryKey)) {
+      continue;
+    }
+    queryKeys.push(queryKey);
+    parentIndexes.push(i);
+  }
+  if (queryKeys.length === 0) {
+    return results;
+  }
+  const implicitKeys = getImplicitKeyFields(selectSpec.select, targetMeta);
+  const projectionExtras = options.updatable ? [...implicitKeys, "PK", "SK"] : implicitKeys;
+  const batchOps = planBatchGetForQueryKeys(
+    targetMeta,
+    queryKeys,
+    selectSpec.select,
+    projectionExtras.length > 0 ? projectionExtras : void 0
+  );
+  const executor = ClientManager.getExecutor();
+  const queryKeyToRaw = /* @__PURE__ */ new Map();
+  for (const operation of batchOps) {
+    const batchResult = await executor.batchGet(operation);
+    for (const item of batchResult.items) {
+      for (const queryKey of queryKeys) {
+        if (!matchesQueryKey(item, queryKey)) {
+          continue;
+        }
+        queryKeyToRaw.set(serializeQueryKey(queryKey), item);
+      }
+    }
+  }
+  const nestedRelations = detectRelationFields(selectSpec.select, targetMeta);
+  const ownPath = relationResultPath(parentPath, rel);
+  await mapWithConcurrency(
+    queryKeys,
+    options.plan?.plan.concurrency ?? RELATION_TRAVERSAL_CONCURRENCY,
+    async (queryKey, j) => {
+      const parentIndex = parentIndexes[j];
+      const raw = queryKeyToRaw.get(serializeQueryKey(queryKey));
+      if (!raw) {
+        return;
+      }
+      const updatable = options.updatable ?? false;
+      let resolvedItem = hydrate([raw], selectSpec.select, targetMeta, updatable)[0] ?? null;
+      if (resolvedItem && nestedRelations.length > 0) {
+        resolvedItem = await resolveRelations(
+          resolvedItem,
+          raw,
+          selectSpec.select,
+          targetMeta,
+          options,
+          currentDepth + 1,
+          ownPath
+        );
+        if (resolvedItem && updatable) {
+          attachHiddenKey(resolvedItem, raw);
+        }
+      }
+      if (resolvedItem && !passesPostLoad(resolvedItem, selectSpec, targetMeta)) {
+        results[parentIndex] = null;
+      } else {
+        results[parentIndex] = resolvedItem;
+      }
+    }
+  );
+  return results;
+}
+function passesPostLoad(item, spec, targetMeta) {
+  if (spec.filter && !evaluateFilterClientSide(item, spec.filter, targetMeta)) {
+    return false;
+  }
+  return true;
+}
+async function resolveSingleValueRelationsBatch(parentItems, rawParentItems, select, metadata, options, currentDepth, parentPath) {
+  const results = parentItems.map((item, i) => {
+    const copy = { ...item };
+    if (options.updatable) {
+      attachHiddenKey(copy, rawParentItems[i]);
+    }
+    return copy;
+  });
+  const relations = detectRelationFields(select, metadata).filter(
+    (rel) => rel.type === "belongsTo" || rel.type === "hasOne"
+  );
+  await runStaged(relations, parentPath, options.plan, async (rel) => {
+    const selectSpec = relationSpec(select[rel.propertyName]);
+    const targetClass = rel.targetFactory();
+    const targetMeta = MetadataRegistry.get(targetClass);
+    const batchResults = await fetchBelongsToHasOneBatch(
+      rel,
+      rawParentItems,
+      selectSpec,
+      targetMeta,
+      options,
+      currentDepth,
+      parentPath
+    );
+    for (let i = 0; i < results.length; i++) {
+      results[i][rel.propertyName] = batchResults[i];
+    }
+  });
+  return results;
+}
+async function resolveRelations(parentItem, rawParentItem, select, metadata, options, currentDepth = 1, currentPath = "$") {
+  const result = { ...parentItem };
+  const relations = detectRelationFields(select, metadata);
+  const plan2 = options.plan ?? (currentPath === "$" ? buildRelationExecutionPlan(select, metadata) : void 0);
+  const opts = plan2 === options.plan ? options : { ...options, plan: plan2 };
+  await runStaged(relations, currentPath, opts.plan, async (rel) => {
+    const selectSpec = relationSpec(select[rel.propertyName]);
+    const ownPath = relationResultPath(currentPath, rel);
+    if (rel.type === "hasMany") {
+      const targetClass2 = rel.targetFactory();
+      const queryKey = buildRelationQueryKey(rel, rawParentItem);
+      const limit = selectSpec.limit ?? rel.options?.limit?.default ?? 20;
+      const order = selectSpec.order ?? rel.options?.order ?? "ASC";
+      const listResult = await executeListInternal(targetClass2, queryKey, {
+        select: selectSpec.select,
+        limit,
+        after: selectSpec.after,
+        order,
+        filter: selectSpec.filter,
+        updatable: opts.updatable
+      });
+      let items = listResult.items;
+      const rawItems = listResult.rawItems;
+      const targetMeta2 = MetadataRegistry.get(targetClass2);
+      const nestedRelations = detectRelationFields(selectSpec.select, targetMeta2);
+      if (nestedRelations.length > 0) {
+        items = await resolveSingleValueRelationsBatch(
+          items,
+          rawItems,
+          selectSpec.select,
+          targetMeta2,
+          opts,
+          currentDepth + 1,
+          ownPath
+        );
+      }
+      result[rel.propertyName] = {
+        items,
+        cursor: listResult.cursor
+      };
+      return;
+    }
+    const targetClass = rel.targetFactory();
+    const targetMeta = MetadataRegistry.get(targetClass);
+    const [resolvedItem] = await fetchBelongsToHasOneBatch(
+      rel,
+      [rawParentItem],
+      selectSpec,
+      targetMeta,
+      opts,
+      currentDepth,
+      currentPath
+    );
+    result[rel.propertyName] = resolvedItem;
+  });
+  return result;
+}
+
+// src/operations/query.ts
+async function executeQuery(modelClass, key2, selectSpec, options) {
+  const metadata = MetadataRegistry.get(modelClass);
+  const queryFields = Object.keys(key2);
+  const resolved = resolveKey(queryFields, metadata);
+  if (resolved.type === "gsi" && !resolved.unique) {
+    throw new Error(
+      `Cannot use query() with non-unique GSI '${resolved.indexName}'. Use list() instead.`
+    );
+  }
+  const normalized = normalizeTopLevelSelect(selectSpec);
+  const select = normalized.select;
+  const filter = normalized.filter;
+  const maxDepth = options?.maxDepth ?? 1;
+  const relations = detectRelationFields(select, metadata);
+  if (relations.length > 0) {
+    validateDepth(select, metadata, maxDepth);
+  }
+  const implicitKeys = getImplicitKeyFields(select, metadata);
+  const updatable = options?.updatable ?? false;
+  const executionPlan = plan(metadata, {
+    key: key2,
+    select,
+    filter,
+    consistentRead: options?.consistentRead,
+    additionalProjectionFields: implicitKeys.length > 0 ? implicitKeys : void 0,
+    updatable
+  });
+  const operation = executionPlan.operations[0];
+  const canParallelizeRelations = relations.length > 0 && relations.every(
+    (rel) => Object.values(rel.keyBinding).every(
+      (sourceField) => key2[sourceField] != null
+    )
+  );
+  const parentPromise = execute(operation);
+  const relationPromise = canParallelizeRelations ? resolveRelations({}, key2, select, metadata, { maxDepth, updatable }, 1) : null;
+  let result;
+  try {
+    result = await parentPromise;
+  } catch (err) {
+    if (relationPromise) await relationPromise.catch(() => void 0);
+    throw err;
+  }
+  if (result.items.length === 0) {
+    if (relationPromise) await relationPromise.catch(() => void 0);
+    return null;
+  }
+  const rawItem = result.items[0];
+  const hydrated = hydrate(result.items, select, metadata, updatable);
+  let hydratedItem = hydrated[0] ?? null;
+  if (hydratedItem && relations.length > 0) {
+    if (relationPromise) {
+      const resolvedRelations = await relationPromise;
+      for (const rel of relations) {
+        hydratedItem[rel.propertyName] = resolvedRelations[rel.propertyName];
+      }
+    } else {
+      hydratedItem = await resolveRelations(
+        hydratedItem,
+        rawItem,
+        select,
+        metadata,
+        { maxDepth, updatable },
+        1
+      );
+      if (hydratedItem && updatable) {
+        attachHiddenKey(hydratedItem, rawItem);
+      }
+    }
+  }
+  if (options?.hydrate) {
+    return options.hydrate(hydratedItem);
+  }
+  return hydratedItem;
+}
+
+// src/operations/explain.ts
+function executeExplain(modelClass, key2, options) {
+  const metadata = MetadataRegistry.get(modelClass);
+  const exclusiveStartKey = options?.after ? decodeCursor(options.after) : void 0;
+  const normalized = normalizeTopLevelSelect(options?.select);
+  const select = normalized.select ?? {};
+  const filter = options?.filter ?? normalized.filter;
+  const mainPlan = plan(metadata, {
+    key: key2,
+    select,
+    limit: options?.limit,
+    after: exclusiveStartKey,
+    order: options?.order,
+    consistentRead: options?.consistentRead,
+    filter
+  });
+  const relationOps = planRelationOperations(metadata, select, {
+    estimatedParentCount: 1
+  });
+  return {
+    operations: [...mainPlan.operations, ...relationOps]
+  };
+}
+
+// src/operations/batch.ts
+var BatchGetResult = class {
+  groups;
+  constructor(groups) {
+    this.groups = groups;
+  }
+  get(model2) {
+    const modelClass = resolveModelClass(model2);
+    return this.groups.get(modelClass) ?? [];
+  }
+};
+function buildScalarSelect(metadata) {
+  const select = {};
+  for (const field2 of metadata.fields) {
+    select[field2.propertyName] = true;
+  }
+  return select;
+}
+function buildDynamoKey(modelClass, keyObj) {
+  const deleteInput = buildDeleteInput(modelClass, keyObj);
+  return deleteInput.Key;
+}
+function hydrateBatchItems(rawItems, metadata) {
+  if (rawItems.length === 0) {
+    return [];
+  }
+  const select = buildScalarSelect(metadata);
+  const hydrated = hydrate(rawItems, select, metadata);
+  if (metadata.embeddedFields.length === 0) {
+    return hydrated;
+  }
+  return hydrated.map((item, index) => {
+    const raw = rawItems[index];
+    const merged = { ...item };
+    for (const emb of metadata.embeddedFields) {
+      const rawEmb = raw?.[emb.propertyName];
+      if (rawEmb !== void 0 && rawEmb !== null) {
+        merged[emb.propertyName] = rawEmb;
+      }
+    }
+    return merged;
+  });
+}
+async function executeBatchGetForTable(tableName, entries) {
+  const groups = /* @__PURE__ */ new Map();
+  if (entries.length === 0) {
+    return groups;
+  }
+  const keys = entries.map((entry) => entry.dynamoKey);
+  const { items: rawItems } = await ClientManager.getExecutor().batchGet({
+    tableName,
+    keys
+  });
+  const entriesByModel = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    const existing = entriesByModel.get(entry.modelClass) ?? [];
+    existing.push(entry);
+    entriesByModel.set(entry.modelClass, existing);
+  }
+  for (const [modelClass, modelEntries] of entriesByModel) {
+    const metadata = modelEntries[0].metadata;
+    const expectedKeys = new Set(
+      modelEntries.map(
+        (entry) => `${String(entry.dynamoKey.PK)}::${String(entry.dynamoKey.SK)}`
+      )
+    );
+    const modelRawItems = rawItems.filter(
+      (item) => expectedKeys.has(`${String(item.PK)}::${String(item.SK)}`)
+    );
+    groups.set(modelClass, hydrateBatchItems(modelRawItems, metadata));
+  }
+  return groups;
+}
+async function executeBatchGet(requests) {
+  const entriesByTable = /* @__PURE__ */ new Map();
+  for (const request of requests) {
+    const modelClass = resolveModelClass(request.model);
+    const metadata = MetadataRegistry.get(modelClass);
+    const tableName = TableMapping.resolve(metadata.tableName);
+    for (const keyObj of request.keys) {
+      const entry = {
+        modelClass,
+        metadata,
+        dynamoKey: buildDynamoKey(modelClass, keyObj)
+      };
+      const existing = entriesByTable.get(tableName) ?? [];
+      existing.push(entry);
+      entriesByTable.set(tableName, existing);
+    }
+  }
+  const mergedGroups = /* @__PURE__ */ new Map();
+  for (const [, entries] of entriesByTable) {
+    const tableName = TableMapping.resolve(entries[0].metadata.tableName);
+    const tableGroups = await executeBatchGetForTable(tableName, entries);
+    for (const [modelClass, items] of tableGroups) {
+      const existing = mergedGroups.get(modelClass) ?? [];
+      mergedGroups.set(modelClass, existing.concat(items));
+    }
+  }
+  return new BatchGetResult(mergedGroups);
+}
+function toExecItem(entry) {
+  if (entry.request.type === "put") {
+    return { type: "put", item: entry.request.putInput.Item };
+  }
+  return { type: "delete", key: entry.request.deleteInput.Key };
+}
+async function executeBatchWrite(requests) {
+  const entriesByTable = /* @__PURE__ */ new Map();
+  for (const request of requests) {
+    const modelClass = resolveModelClass(request.model);
+    const metadata = MetadataRegistry.get(modelClass);
+    const tableName = TableMapping.resolve(metadata.tableName);
+    if (request.type === "put") {
+      const putInput = buildPutInput(modelClass, request.item, request.options);
+      const entry2 = {
+        tableName,
+        modelName: modelClass.name,
+        request: { type: "put", putInput }
+      };
+      const existing2 = entriesByTable.get(tableName) ?? [];
+      existing2.push(entry2);
+      entriesByTable.set(tableName, existing2);
+      continue;
+    }
+    const deleteInput = buildDeleteInput(modelClass, request.key, request.options);
+    const entry = {
+      tableName,
+      modelName: modelClass.name,
+      request: { type: "delete", deleteInput }
+    };
+    const existing = entriesByTable.get(tableName) ?? [];
+    existing.push(entry);
+    entriesByTable.set(tableName, existing);
+  }
+  const executor = ClientManager.getExecutor();
+  for (const [tableName, entries] of entriesByTable) {
+    await executor.batchWrite(tableName, entries.map(toExecItem));
+  }
+  if (ChangeCaptureRegistry.hasSubscribers()) {
+    for (const [, entries] of entriesByTable) {
+      for (const entry of entries) {
+        if (entry.request.type === "put") {
+          const item = entry.request.putInput.Item;
+          captureWrite({
+            table: entry.tableName,
+            ...entry.modelName ? { model: entry.modelName } : {},
+            op: "put",
+            keys: { pk: String(item.PK), sk: String(item.SK ?? "") },
+            newItem: item
+          });
+        } else {
+          const dkey = entry.request.deleteInput.Key;
+          captureWrite({
+            table: entry.tableName,
+            ...entry.modelName ? { model: entry.modelName } : {},
+            op: "delete",
+            keys: { pk: String(dkey.PK), sk: String(dkey.SK ?? "") }
+          });
+        }
+      }
+    }
+  }
+}
+
+// src/model/DDBModel.ts
+var DDBModel = class {
+  static setClient(client) {
+    ClientManager.setClient(client);
+  }
+  static setTableMapping(mapping) {
+    TableMapping.set(mapping);
+  }
+  static async transaction(fn) {
+    await executeTransaction(fn);
+  }
+  static async batchGet(requests) {
+    return executeBatchGet(requests);
+  }
+  static async batchWrite(requests) {
+    return executeBatchWrite(requests);
+  }
+  static asModel() {
+    const modelClass = this;
+    const modelStatic = {
+      col: createColumnMap(),
+      project(select) {
+        return buildProject(select);
+      },
+      relation(select) {
+        return buildRelation(select);
+      },
+      // The public `query` is overloaded (plain / updatable / hydrate, the last
+      // introducing a fresh return-type parameter `R`, issue #53). An overloaded
+      // method on an object literal cannot contextually infer its single
+      // implementation signature, so the implementation is written with explicit
+      // runtime-facing parameter types and assigned through the interface's
+      // method type — the public overloads (the only caller-visible surface)
+      // are untouched.
+      query: ((key2, select, options) => {
+        if (isRecordingContractMethod()) {
+          recordContractOp("query", modelStatic, {
+            keys: key2,
+            select
+          });
+          return Promise.resolve(null);
+        }
+        return executeQuery(modelClass, key2, select, options);
+      }),
+      async list(key2, options) {
+        if (isRecordingContractMethod()) {
+          recordContractOp("list", modelStatic, {
+            keys: key2,
+            select: options?.select
+          });
+          return { items: [], cursor: null };
+        }
+        const result = await executeList(
+          modelClass,
+          key2,
+          options
+        );
+        return result;
+      },
+      explain(key2, options) {
+        return executeExplain(
+          modelClass,
+          key2,
+          options
+        );
+      },
+      async put(item, options) {
+        if (isRecordingContractMethod()) {
+          recordContractOp("put", modelStatic, {
+            item,
+            condition: options?.condition,
+            batch: options?.batch
+          });
+          return;
+        }
+        await executePut(
+          modelClass,
+          item,
+          options
+        );
+      },
+      async update(entity, changes, options) {
+        if (isRecordingContractMethod()) {
+          recordContractOp("update", modelStatic, {
+            keys: entity,
+            changes,
+            condition: options?.condition,
+            batch: options?.batch
+          });
+          return;
+        }
+        await executeUpdate(
+          modelClass,
+          entity,
+          changes,
+          options
+        );
+      },
+      async delete(key2, options) {
+        if (isRecordingContractMethod()) {
+          recordContractOp("delete", modelStatic, {
+            keys: key2,
+            condition: options?.condition,
+            batch: options?.batch
+          });
+          return;
+        }
+        await executeDelete(modelClass, key2, options);
+      }
+    };
+    return attachModelClass(
+      modelStatic,
+      modelClass
+    );
+  }
+};
+
+// src/operations/declarative-transaction.ts
+var PLACEHOLDER_RE = /\{[^{}]+\}/g;
+function resolveTemplate(template, params, element) {
+  return template.replace(PLACEHOLDER_RE, (match) => {
+    const name = match.slice(1, -1);
+    if (name.startsWith("item.")) {
+      const field2 = name.slice("item.".length);
+      if (!element || !(field2 in element)) {
+        throw new Error(
+          `declarative transaction: element field '${field2}' is not bound; template '${template}' is only valid inside a forEach over the array param that supplies '${field2}'.`
+        );
+      }
+      return String(element[field2]);
+    }
+    if (!(name in params) || params[name] === void 0 || params[name] === null) {
+      throw new Error(
+        `declarative transaction: template '${template}' references unbound parameter '${name}'.`
+      );
+    }
+    return String(params[name]);
+  });
+}
+function isWholePlaceholder(template) {
+  return /^\{[^{}]+\}$/.test(template);
+}
+function resolveValue(template, params, element) {
+  if (isWholePlaceholder(template)) {
+    const name = template.slice(1, -1);
+    if (name.startsWith("item.")) {
+      const field2 = name.slice("item.".length);
+      if (element && field2 in element) return element[field2];
+    } else if (name in params) {
+      return params[name];
+    }
+  }
+  return resolveTemplate(template, params, element);
+}
+function resolveRecord(record, params, element) {
+  const out = {};
+  for (const [field2, tmpl] of Object.entries(record ?? {})) {
+    out[field2] = resolveValue(tmpl, params, element);
+  }
+  return out;
+}
+function fillKeyTemplate(template, item) {
+  return template.replace(PLACEHOLDER_RE, (match) => {
+    const name = match.slice(1, -1);
+    return item[name] === void 0 ? "" : String(item[name]);
+  });
+}
+function keyTemplateFillable(template, item) {
+  const matches = template.match(PLACEHOLDER_RE) ?? [];
+  return matches.every((m) => m.slice(1, -1) in item);
+}
+function addKeyAttributes(entity, item) {
+  if (entity.key) {
+    item.PK = fillKeyTemplate(entity.key.pkTemplate, item);
+    if (entity.key.skTemplate !== null) {
+      item.SK = fillKeyTemplate(entity.key.skTemplate, item);
+    }
+  }
+  for (const gsi2 of entity.gsis) {
+    if (keyTemplateFillable(gsi2.pkTemplate, item)) {
+      item[`${gsi2.indexName}PK`] = fillKeyTemplate(gsi2.pkTemplate, item);
+    }
+    if (gsi2.skTemplate !== null && keyTemplateFillable(gsi2.skTemplate, item)) {
+      item[`${gsi2.indexName}SK`] = fillKeyTemplate(gsi2.skTemplate, item);
+    }
+  }
+}
+function whenHolds(when2, params, element) {
+  const left = resolveTemplate(when2.left, params, element);
+  const right = resolveTemplate(when2.right, params, element);
+  return when2.op === "eq" ? left === right : left !== right;
+}
+function applyCondition(condition, target, params, element) {
+  if (!condition) return;
+  const names = target.ExpressionAttributeNames ??= {};
+  if (condition.kind === "notExists") {
+    names["#pk"] = "PK";
+    target.ConditionExpression = "attribute_not_exists(#pk)";
+    return;
+  }
+  if (condition.kind === "attributeExists" || condition.kind === "attributeNotExists") {
+    const fn = condition.kind === "attributeExists" ? "attribute_exists" : "attribute_not_exists";
+    names["#ce"] = condition.field;
+    target.ConditionExpression = `${fn}(#ce)`;
+    return;
+  }
+  const values = target.ExpressionAttributeValues ??= {};
+  const clauses = [];
+  let i = 0;
+  for (const [field2, tmpl] of Object.entries(condition.fields)) {
+    const n = `#e${i}`;
+    const v = `:e${i}`;
+    names[n] = field2;
+    values[v] = resolveValue(tmpl, params, element);
+    clauses.push(`${n} = ${v}`);
+    i++;
+  }
+  target.ConditionExpression = clauses.join(" AND ");
+}
+function entityByName(manifest, name) {
+  const entity = manifest.entities[name];
+  if (!entity) {
+    throw new Error(`declarative transaction: unknown entity '${name}' in manifest.`);
+  }
+  return entity;
+}
+function physicalTableName(manifest, logical) {
+  return manifest.tables[logical]?.physicalName ?? logical;
+}
+function buildTransactItem(spec, manifest, params, element) {
+  const literal2 = spec.literalKey === true;
+  const entity = literal2 ? void 0 : entityByName(manifest, spec.entity);
+  const table = literal2 ? physicalTableName(manifest, spec.tableName) : entity.physicalName;
+  if (spec.type === "Put") {
+    const item = resolveRecord(spec.item, params, element);
+    if (entity) addKeyAttributes(entity, item);
+    const put = { TableName: table, Item: item };
+    applyCondition(spec.condition, put, params, element);
+    return { Put: put };
+  }
+  const key2 = resolveRecord(spec.keyCondition, params, element);
+  if (spec.type === "Delete") {
+    const del = { TableName: table, Key: key2 };
+    applyCondition(spec.condition, del, params, element);
+    return { Delete: del };
+  }
+  if (spec.type === "ConditionCheck") {
+    if (!spec.condition) {
+      throw new Error(
+        `declarative transaction: ConditionCheck on '${spec.entity}' has no condition; a ConditionCheck must carry the assertion it makes.`
+      );
+    }
+    const check = { TableName: table, Key: key2 };
+    applyCondition(spec.condition, check, params, element);
+    return { ConditionCheck: check };
+  }
+  const changes = resolveRecord(spec.changes, params, element);
+  const adds = resolveRecord(spec.add, params, element);
+  const names = {};
+  const values = {};
+  const sets = [];
+  const addClauses = [];
+  let i = 0;
+  for (const [field2, value] of Object.entries(changes)) {
+    const n = `#c${i}`;
+    const v = `:c${i}`;
+    names[n] = field2;
+    values[v] = value;
+    sets.push(`${n} = ${v}`);
+    i++;
+  }
+  let j = 0;
+  for (const [field2, value] of Object.entries(adds)) {
+    const n = `#a${j}`;
+    const v = `:a${j}`;
+    names[n] = field2;
+    values[v] = typeof value === "string" ? Number(value) : value;
+    addClauses.push(`${n} ${v}`);
+    j++;
+  }
+  const update = { TableName: table, Key: key2 };
+  const exprParts = [];
+  if (sets.length > 0) exprParts.push("SET " + sets.join(", "));
+  if (addClauses.length > 0) exprParts.push("ADD " + addClauses.join(", "));
+  if (exprParts.length > 0) {
+    update.UpdateExpression = exprParts.join(" ");
+    update.ExpressionAttributeNames = names;
+    update.ExpressionAttributeValues = values;
+  }
+  applyCondition(spec.condition, update, params, element);
+  return { Update: update };
+}
+function expandTransactionItems(spec, manifest, params) {
+  const expanded = [];
+  const emit = (item, element) => {
+    const model2 = item.literalKey === true || item.entity === MARKER_ROW_ENTITY ? void 0 : item.entity;
+    expanded.push({ item: buildTransactItem(item, manifest, params, element), model: model2 });
+  };
+  for (const item of spec.items) {
+    if (item.forEach) {
+      const source = params[item.forEach.source];
+      if (!Array.isArray(source)) {
+        throw new Error(
+          `declarative transaction: forEach source '${item.forEach.source}' must be an array param; got ${typeof source}.`
+        );
+      }
+      for (const element of source) {
+        if (item.when && !whenHolds(item.when, params, element)) continue;
+        emit(item, element);
+      }
+    } else {
+      if (item.when && !whenHolds(item.when, params, void 0)) continue;
+      emit(item, void 0);
+    }
+  }
+  return expanded;
+}
+function expandTransaction(spec, manifest, params) {
+  const expanded = expandTransactionItems(spec, manifest, params).map((e) => e.item);
+  const out = collapseSameKeyItems(
+    expanded
+  );
+  if (out.length > MAX_TRANSACT_ITEMS) {
+    throw new Error(
+      `declarative transaction: expanded to ${out.length} items, exceeds the DynamoDB TransactWriteItems limit of ${MAX_TRANSACT_ITEMS}.`
+    );
+  }
+  return out;
+}
+async function executeDeclarativeTransaction(spec, manifest, params) {
+  const expanded = expandTransactionItems(spec, manifest, params);
+  if (expanded.length === 0) return;
+  const modelBySignature = /* @__PURE__ */ new Map();
+  for (const { item, model: model2 } of expanded) {
+    if (model2 !== void 0) {
+      modelBySignature.set(
+        execItemKeySignature(item),
+        model2
+      );
+    }
+  }
+  await commitTransaction(
+    expanded.map((e) => e.item),
+    {
+      modelBySignature,
+      limitError: (count) => new Error(
+        `declarative transaction: expanded to ${count} items, exceeds the DynamoDB TransactWriteItems limit of ${MAX_TRANSACT_ITEMS}.`
+      )
+    }
+  );
+}
+
+// src/runtime/per-key-cursor.ts
+function serializeContractKey(key2) {
+  const sortedEntries = Object.keys(key2).sort().map((field2) => [field2, key2[field2]]);
+  return JSON.stringify(Object.fromEntries(sortedEntries));
+}
+function encodePerKeyCursor(key2, inner) {
+  if (inner === null) return null;
+  const envelope = {
+    key: serializeContractKey(key2),
+    inner
+  };
+  return encodeCursor(envelope);
+}
+function decodePerKeyCursor(cursor, expectedKey) {
+  let envelope;
+  try {
+    envelope = decodeCursor(cursor);
+  } catch {
+    throw new Error(
+      `Invalid per-key cursor: the value passed as \`after\` is not a cursor minted by this runtime (it failed to decode).`
+    );
+  }
+  if (typeof envelope !== "object" || envelope === null || typeof envelope.key !== "string" || typeof envelope.inner !== "string") {
+    throw new Error(
+      `Invalid per-key cursor: the decoded envelope is missing its key / inner fields. A range cursor must be a per-key envelope minted by this runtime.`
+    );
+  }
+  const expected = serializeContractKey(expectedKey);
+  if (envelope.key !== expected) {
+    throw new Error(
+      `Per-key cursor mismatch: the supplied \`after\` cursor belongs to key ${envelope.key}, but the method is being called for key ${expected}. A range cursor may only resume pagination of the same key it was issued for.`
+    );
+  }
+  return envelope.inner;
+}
+
+// src/runtime/contract-runtime.ts
+var CONTRACT_RANGE_FANOUT_CONCURRENCY = RELATION_TRAVERSAL_CONCURRENCY;
+function resolveQueryMethod(contract, methodName) {
+  const method = contract.methods[methodName];
+  if (method === void 0) {
+    throw new Error(
+      `Contract runtime: query method '${methodName}' does not exist on this contract. Available methods: ${Object.keys(contract.methods).sort().join(", ") || "(none)"}.`
+    );
+  }
+  return method;
+}
+function modelClassOf(op) {
+  return op.entity.modelClass;
+}
+function selectOf(op) {
+  return op.select ?? {};
+}
+async function executePointSingle(op, key2, params) {
+  return executeQuery(modelClassOf(op), key2, selectOf(op), {
+    consistentRead: params.consistentRead
+  });
+}
+async function executeRangeSingle(op, key2, params) {
+  const innerAfter = params.after !== void 0 ? decodePerKeyCursor(params.after, key2) : void 0;
+  const result = await executeListInternal(modelClassOf(op), key2, {
+    select: selectOf(op),
+    limit: params.limit,
+    after: innerAfter,
+    order: params.order
+  });
+  return {
+    items: result.items,
+    cursor: encodePerKeyCursor(key2, result.cursor)
+  };
+}
+async function executePointBatch(op, keys, _params) {
+  return executeKeyedBatchGet(modelClassOf(op), keys, selectOf(op));
+}
+async function executeKeyedBatchGet(modelClass, keys, select) {
+  const metadata = MetadataRegistry.get(modelClass);
+  const tableName = TableMapping.resolve(metadata.tableName);
+  const resolved = keys.map((key2) => {
+    const dynamoKey = buildDeleteInput(modelClass, key2).Key;
+    return { id: serializeContractKey(key2), dynamoKey, marker: dynamoKeyMarker(dynamoKey) };
+  });
+  const uniqueByMarker = /* @__PURE__ */ new Map();
+  for (const r of resolved) {
+    if (!uniqueByMarker.has(r.marker)) uniqueByMarker.set(r.marker, r.dynamoKey);
+  }
+  const rawByMarker = /* @__PURE__ */ new Map();
+  const uniqueKeys = [...uniqueByMarker.values()];
+  if (uniqueKeys.length > 0) {
+    const { items } = await ClientManager.getExecutor().batchGet({
+      tableName,
+      keys: uniqueKeys
+    });
+    for (const raw of items) {
+      rawByMarker.set(dynamoKeyMarker(raw), raw);
+    }
+  }
+  const out = /* @__PURE__ */ new Map();
+  for (const r of resolved) {
+    if (out.has(r.id)) continue;
+    const raw = rawByMarker.get(r.marker);
+    out.set(r.id, raw !== void 0 ? hydrateOne(raw, select, metadata) : null);
+  }
+  return out;
+}
+function dynamoKeyMarker(keyOrItem) {
+  return `${String(keyOrItem.PK)}::${String(keyOrItem.SK ?? "")}`;
+}
+function hydrateOne(raw, select, metadata) {
+  return hydrate([raw], select, metadata)[0];
+}
+async function executeQueryMethod(contract, methodName, keyOrKeys, params = {}) {
+  const method = resolveQueryMethod(contract, methodName);
+  if (Array.isArray(keyOrKeys)) {
+    if (method.inputArity === "single") {
+      const kind = method.resolution === "range" ? "range" : "unique-GSI point";
+      throw new Error(
+        `Contract runtime: ${kind} method '${methodName}' was called with an array of keys, but its inputArity is 'single'. A ${kind} resolution is one ${method.resolution === "range" ? "partition" : "GSI"} Query per key, so an array would be an N+1 fan-out \u2014 forbidden by the contract's N+1 rule. Loop in application code if you genuinely need N independent reads.`
+      );
+    }
+    const keyed = await executePointBatch(method.op, keyOrKeys, params);
+    await resolveCompositions(method.op, [...keyed.values()].filter(isRecord));
+    return keyed;
+  }
+  const key2 = keyOrKeys;
+  if (method.resolution === "point") {
+    const item = await executePointSingle(method.op, key2, params);
+    if (item !== null) await resolveCompositions(method.op, [item]);
+    return item;
+  }
+  const connection = await executeRangeSingle(method.op, key2, params);
+  await resolveCompositions(method.op, connection.items.filter(isRecord));
+  return connection;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+async function resolveCompositions(op, parents, plan2) {
+  const compose = op.compose;
+  if (compose === void 0 || compose.length === 0 || parents.length === 0) return;
+  const resolved = plan2 ?? deriveCompositionPlan(compose.length);
+  for (const stage of resolved.stages) {
+    await mapWithConcurrency(
+      stage.map((i) => compose[i]),
+      resolved.concurrency,
+      (edge) => resolveComposition(edge, parents)
+    );
+  }
+}
+async function resolveComposition(edge, parents) {
+  const childMethod = edge.method;
+  if (childMethod.resolution !== "point") {
+    throw new Error(
+      `Contract runtime: composed child '${edge.as}' resolves to a 'range' method, but an External Query child must be 'point' so it coalesces to one BatchGetItem across all parent records. A range child is an N+1 fan-out (it is rejected at build time by the N+1 checker).`
+    );
+  }
+  const childOp = childMethod.op;
+  const childSelect = selectOf(childOp);
+  const bindFields = Object.keys(edge.bind);
+  const bound = [];
+  const childKeys = [];
+  for (const parent of parents) {
+    const childKey = {};
+    let complete = true;
+    for (const field2 of bindFields) {
+      const value = readFromPath(parent, edge.bind[field2].path);
+      if (value === void 0 || value === null) {
+        complete = false;
+        break;
+      }
+      childKey[field2] = value;
+    }
+    if (!complete) {
+      parent[edge.as] = null;
+      continue;
+    }
+    bound.push({ parent, childKey, keyId: serializeContractKey(childKey) });
+    childKeys.push(childKey);
+  }
+  if (childKeys.length === 0) return;
+  const childResults = await executeKeyedBatchGet(
+    modelClassOf(childOp),
+    childKeys,
+    childSelect
+  );
+  for (const { parent, keyId } of bound) {
+    const child = childResults.get(keyId);
+    parent[edge.as] = child ?? null;
+  }
+}
+function readFromPath(record, path) {
+  if (path === "$") return record;
+  const segments = path.slice(2).split(".");
+  let current = record;
+  for (const segment of segments) {
+    if (typeof current !== "object" || current === null) return void 0;
+    current = current[segment];
+  }
+  return current;
+}
+async function executeRangeFanout(op, keys, params = {}) {
+  const connections = await mapWithConcurrency(
+    keys,
+    CONTRACT_RANGE_FANOUT_CONCURRENCY,
+    (key2) => executeRangeSingle(op, key2, params)
+  );
+  const out = /* @__PURE__ */ new Map();
+  keys.forEach((key2, i) => {
+    out.set(serializeContractKey(key2), connections[i]);
+  });
+  return out;
+}
+
+// src/runtime/command-runtime.ts
+function resolveCommandMethod(contract, methodName) {
+  const method = contract.methods[methodName];
+  if (method === void 0) {
+    throw new Error(
+      `Contract runtime: command method '${methodName}' does not exist on this contract. Available methods: ${Object.keys(contract.methods).sort().join(", ") || "(none)"}.`
+    );
+  }
+  return method;
+}
+function modelClassOf2(op) {
+  return op.entity.modelClass;
+}
+function modelStaticOf(op) {
+  return op.entity.modelClass.asModel();
+}
+function renderLeaf(leaf, key2, params, context) {
+  if (isContractParamRef(leaf)) {
+    if (!(leaf.field in params)) {
+      throw new Error(
+        `Contract runtime: ${context} references params field '${leaf.field}', which was not supplied. Pass it in the method's params argument.`
+      );
+    }
+    return params[leaf.field];
+  }
+  if (isContractKeyFieldRef(leaf)) {
+    if (leaf.field in key2) return key2[leaf.field];
+    if (leaf.field in params) return params[leaf.field];
+    throw new Error(
+      `Contract runtime: ${context} references key field '${leaf.field}', which was not supplied. Pass it in the method's key or params argument.`
+    );
+  }
+  return leaf;
+}
+function renderRecord(structure, key2, params, context) {
+  const out = {};
+  if (structure === void 0) return out;
+  for (const [field2, leaf] of Object.entries(structure)) {
+    out[field2] = renderLeaf(leaf, key2, params, `${context} field '${field2}'`);
+  }
+  return out;
+}
+function renderCondition(condition, key2, params, context) {
+  if (condition === void 0) return void 0;
+  if (typeof condition === "object" && condition !== null) {
+    const obj = condition;
+    if (obj.notExists === true) return { notExists: true };
+    if (typeof obj.attributeExists === "string") {
+      return { attributeExists: obj.attributeExists };
+    }
+    if (typeof obj.attributeNotExists === "string") {
+      return { attributeNotExists: obj.attributeNotExists };
+    }
+  }
+  return renderRecord(
+    condition,
+    key2,
+    params,
+    `${context} condition`
+  );
+}
+function renderWrite(op, key2, params, contextLabel) {
+  if (!isContractKeyRef(op.keys) && op.operation !== "put") {
+    throw new Error(
+      `Contract runtime: ${contextLabel} did not pass the contract key directly into its '${op.operation}' key position. A command method must call \`Model.${op.operation}(keys, \u2026)\` with the key whole.`
+    );
+  }
+  const base = {
+    operation: op.operation,
+    modelClass: modelClassOf2(op),
+    modelStatic: modelStaticOf(op),
+    key: key2,
+    condition: renderCondition(op.condition, key2, params, contextLabel)
+  };
+  if (op.operation === "put") {
+    return { ...base, item: renderRecord(op.item, key2, params, `${contextLabel} item`) };
+  }
+  if (op.operation === "update") {
+    return { ...base, changes: renderRecord(op.changes, key2, params, `${contextLabel} changes`) };
+  }
+  return base;
+}
+async function executeSingleWrite(w) {
+  const options = w.condition !== void 0 ? { condition: w.condition } : void 0;
+  if (w.operation === "put") {
+    await executePut(w.modelClass, w.item ?? {}, options);
+    return;
+  }
+  if (w.operation === "update") {
+    await executeUpdate(w.modelClass, w.key, w.changes ?? {}, options);
+    return;
+  }
+  await executeDelete(w.modelClass, w.key, options);
+}
+async function readBackProjection(write, returnSelection) {
+  const select = {};
+  for (const field2 of Object.keys(returnSelection)) {
+    if (returnSelection[field2] === true) select[field2] = true;
+  }
+  const key2 = readBackKey(write);
+  return executeQuery(write.modelClass, key2, select, { consistentRead: true });
+}
+function readBackKey(write) {
+  if (write.operation !== "put") return write.key;
+  const metadata = MetadataRegistry.get(write.modelClass);
+  const item = write.item ?? {};
+  const key2 = {};
+  const fields = metadata.primaryKey ? metadata.primaryKey.inputFieldNames : Object.keys(item);
+  for (const field2 of fields) {
+    if (field2 in item) key2[field2] = item[field2];
+  }
+  return key2;
+}
+function renderConditionCheck(check, key2, params, contextLabel) {
+  const modelClass = check.entity.modelClass;
+  const referencedKey = {};
+  for (const [targetField, inputField] of Object.entries(check.keyBinding)) {
+    if (inputField in params) {
+      referencedKey[targetField] = params[inputField];
+    } else if (inputField in key2) {
+      referencedKey[targetField] = key2[inputField];
+    } else {
+      throw new Error(
+        `Contract runtime: ${contextLabel} asserts '${check.entity.name}' exists, keyed by input field '${inputField}', which was not supplied. Pass it in the method's params (or key) argument.`
+      );
+    }
+  }
+  const { TableName, Key } = buildDeleteInput(
+    modelClass,
+    referencedKey
+  );
+  const cond2 = buildConditionExpression({ attributeExists: "PK" });
+  const checkInput = {
+    TableName,
+    Key,
+    ConditionExpression: cond2.expression
+  };
+  if (Object.keys(cond2.names).length > 0) checkInput.ExpressionAttributeNames = cond2.names;
+  if (Object.keys(cond2.values).length > 0) checkInput.ExpressionAttributeValues = cond2.values;
+  return checkInput;
+}
+var RUNTIME_TOKEN_RE = /\{([^{}]+)\}/g;
+function renderTemplate(template, key2, params, contextLabel) {
+  const resolveToken = (token) => {
+    if (token in params) return params[token];
+    if (token in key2) return key2[token];
+    throw new Error(
+      `Contract runtime: ${contextLabel} references input field '${token}', which was not supplied. Pass it in the method's params (or key) argument` + (token.startsWith("old.") ? ` \u2014 an \`old.*\` token is the pre-mutation value of a foreign key on an onUpdateKeyChange (pass it as \`{ '${token}': \u2026 }\`).` : `.`)
+    );
+  };
+  const whole = /^\{([^{}]+)\}$/.exec(template);
+  if (whole !== null) return resolveToken(whole[1]);
+  return template.replace(RUNTIME_TOKEN_RE, (_m, token) => String(resolveToken(token)));
+}
+function renderTemplateRecord(record, key2, params, contextLabel) {
+  const out = {};
+  for (const [field2, template] of Object.entries(record ?? {})) {
+    out[field2] = renderTemplate(template, key2, params, contextLabel);
+  }
+  return out;
+}
+function renderEdgeWriteItems(edge, key2, params, contextLabel, modelBySignature) {
+  const adjacency = edge.entity.modelClass;
+  return edge.items.map((item) => {
+    if (item.type === "Put") {
+      const rendered = renderTemplateRecord(item.item, key2, params, `${contextLabel} edge Put`);
+      const out2 = { Put: buildPutInput(adjacency, rendered) };
+      modelBySignature?.set(execItemKeySignature(out2), adjacency.name);
+      return out2;
+    }
+    const renderedKey = renderTemplateRecord(
+      item.keyCondition,
+      key2,
+      params,
+      `${contextLabel} edge Delete`
+    );
+    const del = {
+      TableName: TableMapping.resolve(item.tableName),
+      Key: renderedKey
+    };
+    const out = { Delete: del };
+    modelBySignature?.set(execItemKeySignature(out), adjacency.name);
+    return out;
+  });
+}
+function renderDerivedUpdate(update, key2, params, contextLabel, modelBySignature) {
+  const metadata = MetadataRegistry.get(update.entity.modelClass);
+  if (!metadata.primaryKey) {
+    throw new Error(
+      `Contract runtime: ${contextLabel} derives a counter update on '${update.entity.name}', which has no primary key.`
+    );
+  }
+  const keyInput = {};
+  for (const [targetField, inputField] of Object.entries(update.keyBinding)) {
+    keyInput[targetField] = renderTemplate(
+      `{${inputField}}`,
+      key2,
+      params,
+      `${contextLabel} derived-update key`
+    );
+  }
+  const { TableName, Key } = buildDeleteInput(
+    update.entity.modelClass,
+    keyInput
+  );
+  const updateInput = {
+    TableName,
+    Key,
+    UpdateExpression: "ADD #a0 :a0",
+    ExpressionAttributeNames: { "#a0": update.attribute },
+    ExpressionAttributeValues: { ":a0": update.amount }
+  };
+  const out = { Update: updateInput };
+  modelBySignature?.set(execItemKeySignature(out), update.entity.modelClass.name);
+  return out;
+}
+function renderUniqueGuardItems(guard, key2, params, contextLabel) {
+  return guard.items.map((item) => {
+    if (item.type === "Put") {
+      const Item = renderTemplateRecord(item.item, key2, params, `${contextLabel} guard Put`);
+      const put = { TableName: TableMapping.resolve(item.tableName), Item };
+      const cond2 = buildConditionExpression({ attributeNotExists: "PK" });
+      put.ConditionExpression = cond2.expression;
+      if (Object.keys(cond2.names).length > 0) put.ExpressionAttributeNames = cond2.names;
+      if (Object.keys(cond2.values).length > 0) put.ExpressionAttributeValues = cond2.values;
+      return { Put: put };
+    }
+    const Key = renderTemplateRecord(item.keyCondition, key2, params, `${contextLabel} guard Delete`);
+    const del = { TableName: TableMapping.resolve(item.tableName), Key };
+    return { Delete: del };
+  });
+}
+function renderOutboxEventItems(event, key2, params, contextLabel) {
+  return event.items.map((item) => {
+    const Item = renderTemplateRecord(item.item, key2, params, `${contextLabel} outbox Put`);
+    const put = { TableName: TableMapping.resolve(item.tableName), Item };
+    return { Put: put };
+  });
+}
+function renderIdempotencyGuardItems(guard, key2, params, contextLabel) {
+  return guard.items.map((item) => {
+    const Item = renderTemplateRecord(item.item, key2, params, `${contextLabel} idempotency Put`);
+    const put = { TableName: TableMapping.resolve(item.tableName), Item };
+    const cond2 = buildConditionExpression({ attributeNotExists: "PK" });
+    put.ConditionExpression = cond2.expression;
+    if (Object.keys(cond2.names).length > 0) put.ExpressionAttributeNames = cond2.names;
+    if (Object.keys(cond2.values).length > 0) put.ExpressionAttributeValues = cond2.values;
+    return { Put: put };
+  });
+}
+async function executeReferentialTransaction(writes, edgeItems, updateItems, guardItemsRaw, outboxItems, idempotencyItems, checks, methodName, modelBySignature = /* @__PURE__ */ new Map()) {
+  const writeItems = writes.map((w) => {
+    const options = w.condition !== void 0 ? { condition: w.condition } : void 0;
+    let item;
+    if (w.operation === "put") {
+      item = { Put: buildPutInput(w.modelClass, w.item ?? {}, options) };
+    } else if (w.operation === "update") {
+      item = { Update: buildUpdateInput(w.modelClass, w.key, w.changes ?? {}, options) };
+    } else {
+      item = { Delete: buildDeleteInput(w.modelClass, w.key, options) };
+    }
+    modelBySignature.set(execItemKeySignature(item), w.modelClass.name);
+    return item;
+  });
+  const checkItems = checks.map((c) => ({ ConditionCheck: c.check }));
+  await commitTransaction(
+    [
+      ...writeItems,
+      ...edgeItems,
+      ...updateItems,
+      ...guardItemsRaw,
+      ...outboxItems,
+      ...idempotencyItems,
+      ...checkItems
+    ],
+    {
+      modelBySignature,
+      limitError: (count) => new Error(
+        `Contract runtime: command method '${methodName}' composes ${count} items (writes + edges + derived updates + uniqueness guards + outbox events + idempotency guard + ConditionChecks) into one TransactWriteItems, but DynamoDB caps a transaction at ${MAX_TRANSACT_ITEMS} items and a transaction is atomic \u2014 it cannot be split. Reduce the fragment / effect count.`
+      )
+    }
+  );
+}
+async function executeTransactWrites(writes, methodName) {
+  if (writes.length === 0) return;
+  const modelBySignature = /* @__PURE__ */ new Map();
+  const transactItems = writes.map((w) => {
+    const options = w.condition !== void 0 ? { condition: w.condition } : void 0;
+    let item;
+    if (w.operation === "put") {
+      item = { Put: buildPutInput(w.modelClass, w.item ?? {}, options) };
+    } else if (w.operation === "update") {
+      item = { Update: buildUpdateInput(w.modelClass, w.key, w.changes ?? {}, options) };
+    } else {
+      item = { Delete: buildDeleteInput(w.modelClass, w.key, options) };
+    }
+    modelBySignature.set(execItemKeySignature(item), w.modelClass.name);
+    return item;
+  });
+  await commitTransaction(transactItems, {
+    modelBySignature,
+    limitError: (count) => new Error(
+      `Contract runtime: command method '${methodName}' resolves an array of ${count} keys to a 'transact' (TransactWriteItems) batch, but DynamoDB caps a transaction at ${MAX_TRANSACT_ITEMS} items and a transaction is atomic \u2014 it cannot be split across requests without breaking atomicity. Pass \u2264${MAX_TRANSACT_ITEMS} keys, or declare \`batch: 'batchWrite'\` (a non-atomic BatchWriteItem, chunked automatically) if atomicity is not required.`
+    )
+  });
+}
+async function executeBatchWrites(writes, methodName) {
+  if (writes.length === 0) return;
+  const requests = writes.map((w) => {
+    if (w.operation === "put") {
+      return { type: "put", model: w.modelStatic, item: w.item ?? {} };
+    }
+    if (w.operation === "delete") {
+      return { type: "delete", model: w.modelStatic, key: w.key };
+    }
+    throw new Error(
+      `Contract runtime: command method '${methodName}' resolves to an 'update', but \`batch: 'batchWrite'\` only supports put / delete (DynamoDB's BatchWriteItem has no Update request). Declare \`batch: 'transact'\` for a batched update.`
+    );
+  });
+  await executeBatchWrite(requests);
+}
+async function executeCommandMethod(contract, methodName, keyOrKeys, params = {}) {
+  const method = resolveCommandMethod(contract, methodName);
+  if (Array.isArray(keyOrKeys)) {
+    const keys = keyOrKeys;
+    if (method.ops !== void 0 && method.ops.length > 1) {
+      throw new Error(
+        `Contract runtime: command method '${methodName}' is a multi-fragment mutation (it composes ${method.ops.length} fragments into one atomic TransactWriteItems) and accepts a single key only. Call it once per target, not with a key array.`
+      );
+    }
+    const hasDerivedEffects2 = method.conditionChecks !== void 0 && method.conditionChecks.length > 0 || method.edgeWrites !== void 0 && method.edgeWrites.length > 0 || method.derivedUpdates !== void 0 && method.derivedUpdates.length > 0 || method.uniqueGuards !== void 0 && method.uniqueGuards.length > 0 || method.outboxEvents !== void 0 && method.outboxEvents.length > 0 || method.idempotencyGuard !== void 0;
+    if (hasDerivedEffects2) {
+      throw new Error(
+        `Contract runtime: command method '${methodName}' carries derived effects (referential integrity / edge writes / derived counters / uniqueness guards / outbox events / idempotency guard \u2014 it composes its write + those items into one atomic TransactWriteItems) and accepts a single key only. Call it once per target, not with a key array.`
+      );
+    }
+    if (method.batch === void 0) {
+      throw new Error(
+        `Contract runtime: command method '${methodName}' was called with an array of keys, but it declares no batched-write form. Declare \`batch: 'transact'\` (atomic TransactWriteItems, \u226425) or \`batch: 'batchWrite'\` (non-atomic BatchWriteItem) on the method body, or call it with a single key.`
+      );
+    }
+    const writes = keys.map(
+      (key3, i) => renderWrite(method.op, key3, params, `command method '${methodName}' (key #${i})`)
+    );
+    if (method.batch === "transact") {
+      await executeTransactWrites(writes, methodName);
+    } else {
+      await executeBatchWrites(writes, methodName);
+    }
+    return;
+  }
+  const key2 = keyOrKeys;
+  const conditionChecks = method.conditionChecks ?? [];
+  const edgeWrites2 = method.edgeWrites ?? [];
+  const derivedUpdates = method.derivedUpdates ?? [];
+  const uniqueGuards = method.uniqueGuards ?? [];
+  const outboxEvents = method.outboxEvents ?? [];
+  const idempotencyGuard = method.idempotencyGuard;
+  const hasDerivedEffects = conditionChecks.length > 0 || edgeWrites2.length > 0 || derivedUpdates.length > 0 || uniqueGuards.length > 0 || outboxEvents.length > 0 || idempotencyGuard !== void 0;
+  const isMultiFragment = method.ops !== void 0 && method.ops.length > 1;
+  if (isMultiFragment || hasDerivedEffects) {
+    const ops = method.ops ?? [method.op];
+    const writes = ops.map(
+      (opn, i) => renderWrite(opn, key2, params, `command method '${methodName}' (fragment #${i})`)
+    );
+    if (hasDerivedEffects) {
+      const modelBySignature = /* @__PURE__ */ new Map();
+      const edgeItems = edgeWrites2.flatMap(
+        (edge, i) => renderEdgeWriteItems(
+          edge,
+          key2,
+          params,
+          `command method '${methodName}' (edge #${i})`,
+          modelBySignature
+        )
+      );
+      const updateItems = derivedUpdates.map(
+        (update, i) => renderDerivedUpdate(
+          update,
+          key2,
+          params,
+          `command method '${methodName}' (derive #${i})`,
+          modelBySignature
+        )
+      );
+      const guardItems = uniqueGuards.flatMap(
+        (guard, i) => renderUniqueGuardItems(guard, key2, params, `command method '${methodName}' (unique #${i})`)
+      );
+      const outboxItems = outboxEvents.flatMap(
+        (event, i) => renderOutboxEventItems(event, key2, params, `command method '${methodName}' (emit #${i})`)
+      );
+      const idempotencyItems = idempotencyGuard !== void 0 ? renderIdempotencyGuardItems(
+        idempotencyGuard,
+        key2,
+        params,
+        `command method '${methodName}' (idempotency)`
+      ) : [];
+      const checks = conditionChecks.map((check, i) => ({
+        check: renderConditionCheck(
+          check,
+          key2,
+          params,
+          `command method '${methodName}' (requires #${i})`
+        )
+      }));
+      await executeReferentialTransaction(
+        writes,
+        edgeItems,
+        updateItems,
+        guardItems,
+        outboxItems,
+        idempotencyItems,
+        checks,
+        methodName,
+        modelBySignature
+      );
+    } else {
+      await executeTransactWrites(writes, methodName);
+    }
+    if (method.returnSelection !== void 0 && Object.keys(method.returnSelection).length > 0) {
+      return readBackProjection(writes[0], method.returnSelection);
+    }
+    return;
+  }
+  const write = renderWrite(method.op, key2, params, `command method '${methodName}'`);
+  await executeSingleWrite(write);
+  if (method.returnSelection !== void 0 && Object.keys(method.returnSelection).length > 0) {
+    return readBackProjection(write, method.returnSelection);
+  }
+}
+
+// src/linter/rules/query-boundary.ts
+var queryBoundaryRule = {
+  id: "query-boundary",
+  severity: "error",
+  check(metadata) {
+    const results = [];
+    for (const gsi2 of metadata.gsiDefinitions) {
+      if (!gsi2.unique) {
+        results.push({
+          ruleId: "query-boundary",
+          severity: "error",
+          message: `GSI '${gsi2.indexName}' on entity '${metadata.prefix}' is not marked as unique. Using query() on a non-unique GSI may return multiple items. Use list() instead, or mark the GSI as unique if it guarantees single results.`,
+          entity: metadata.prefix,
+          field: gsi2.indexName
+        });
+      }
+    }
+    return results;
+  }
+};
+
+// src/define/define.ts
+function collectParams(structure, out = {}) {
+  if (structure === null || typeof structure !== "object") return out;
+  for (const [key2, value] of Object.entries(structure)) {
+    if (isParam(value)) {
+      out[key2] = descriptorFromParam(key2, value, out[key2]);
+    } else if (value !== null && typeof value === "object") {
+      collectParams(value, out);
+    }
+  }
+  return out;
+}
+function descriptorFromParam(name, value, existing) {
+  const descriptor = value.literals === void 0 ? { kind: value.kind, required: true } : { kind: value.kind, literals: value.literals, required: true };
+  if (existing !== void 0 && existing.kind !== descriptor.kind) {
+    throw new Error(
+      `Parameter '${name}' is declared with conflicting types ('${existing.kind}' and '${descriptor.kind}'). A parameter name must have a single type across a definition.`
+    );
+  }
+  return descriptor;
+}
+function entityRef(model2) {
+  const modelClass = resolveModelClass(model2);
+  return { name: modelClass.name, modelClass };
+}
+function collectConditionParams(condition, out) {
+  if (condition === void 0) return;
+  const obj = condition;
+  if (obj.notExists === true) return;
+  if (typeof obj.attributeExists === "string") return;
+  if (typeof obj.attributeNotExists === "string") return;
+  collectParams(condition, out);
+}
+function makeDefinition(model2, operation, key2, select, changes, condition) {
+  const params = collectParams(key2);
+  if (changes !== void 0) collectParams(changes, params);
+  collectConditionParams(condition, params);
+  return {
+    __isOperationDefinition: true,
+    entity: entityRef(model2),
+    operation,
+    key: key2,
+    select,
+    changes,
+    ...condition !== void 0 ? { condition } : {},
+    params
+  };
+}
+function defineQuery(model2, key2, select) {
+  return makeDefinition(
+    model2,
+    "query",
+    key2,
+    select,
+    void 0
+  );
+}
+function defineList(model2, key2, select) {
+  return makeDefinition(
+    model2,
+    "list",
+    key2,
+    select,
+    void 0
+  );
+}
+function definePut(model2, item, options) {
+  return makeDefinition(
+    model2,
+    "put",
+    item,
+    void 0,
+    void 0,
+    options?.condition
+  );
+}
+function defineUpdate(model2, key2, changes, options) {
+  return makeDefinition(
+    model2,
+    "update",
+    key2,
+    void 0,
+    changes,
+    options?.condition
+  );
+}
+function defineDelete(model2, key2, options) {
+  return makeDefinition(
+    model2,
+    "delete",
+    key2,
+    void 0,
+    void 0,
+    options?.condition
+  );
+}
+function defineQueries(definitions) {
+  for (const [name, def] of Object.entries(definitions)) {
+    assertDefinition(name, def);
+    if (def.operation !== "query" && def.operation !== "list") {
+      throw new Error(
+        `defineQueries: '${name}' is a '${def.operation}' operation; only query/list definitions are allowed. Use defineCommands for writes.`
+      );
+    }
+  }
+  return definitions;
+}
+function defineCommands(definitions) {
+  for (const [name, def] of Object.entries(definitions)) {
+    assertDefinition(name, def);
+    if (def.operation !== "put" && def.operation !== "update" && def.operation !== "delete") {
+      throw new Error(
+        `defineCommands: '${name}' is a '${def.operation}' operation; only put/update/delete definitions are allowed. Use defineQueries for reads.`
+      );
+    }
+  }
+  return definitions;
+}
+function assertDefinition(name, def) {
+  if (def === null || typeof def !== "object" || def.__isOperationDefinition !== true) {
+    throw new Error(
+      `'${name}' is not a definition. Use defineQuery / defineList / definePut / defineUpdate / defineDelete to build entries.`
+    );
+  }
+}
+export {
+  BATCH_GET_MAX_KEYS,
+  BATCH_WRITE_MAX_ITEMS,
+  BatchGetResult,
+  CONTRACT_RANGE_FANOUT_CONCURRENCY,
+  CdcEmulator,
+  ClientManager,
+  DDBModel,
+  DynamoExecutor,
+  EDGE_WRITES_MARKER,
+  ENTITY_WRITES_MARKER,
+  LIFECYCLE_CONTRACT_MARKER,
+  Linter,
+  MAX_TRANSACT_ITEMS,
+  MetadataRegistry,
+  OLD_VALUE_NAMESPACE,
+  SPEC_VERSION,
+  TableMapping,
+  TransactionContext,
+  assertBundleSerializable,
+  assertContractBoundaries,
+  assertContractN1Safe,
+  assertJsonSerializable,
+  assertSupportedCondition,
+  attachModelClass,
+  belongsTo,
+  binary,
+  boolean,
+  buildBridgeBundle,
+  buildConditionExpression,
+  buildContexts,
+  buildContracts,
+  buildDeleteInput,
+  buildManifest,
+  buildOperations,
+  buildProjection,
+  buildPutInput,
+  buildQuerySpec,
+  buildTransactionSpec,
+  buildTransactions,
+  buildUpdateExpression,
+  buildUpdateInput,
+  collectContractBoundaryViolations,
+  collectContractN1Violations,
+  command,
+  compileFilterExpression,
+  compileFragment,
+  compileMutationPlan,
+  compileSingleFragmentPlan,
+  cond,
+  contractOfMethodSpec,
+  createCdcEmulator,
+  createDefaultLinter,
+  datetime,
+  decodeCursor,
+  decodePerKeyCursor,
+  defineCommands,
+  defineDelete,
+  defineList,
+  definePlan,
+  definePut,
+  defineQueries,
+  defineQuery,
+  defineTransaction,
+  defineTransactions,
+  defineUpdate,
+  deriveEdgeWriteItems,
+  deriveEdgeWriteItemsFor,
+  deriveModelEdgeWriteItems,
+  derivePrefix,
+  detectRelationFields,
+  edgeWrites,
+  embedded,
+  encodeCursor,
+  encodePerKeyCursor,
+  entityWrites,
+  evaluateFilter,
+  execute,
+  executeBatchGet,
+  executeBatchWrite,
+  executeCommandMethod,
+  executeDeclarativeTransaction,
+  executeDelete,
+  executeExplain,
+  executeKeyedBatchGet,
+  executeList,
+  executePut,
+  executeQuery,
+  executeQueryMethod,
+  executeRangeFanout,
+  executeTransaction,
+  executeUpdate,
+  expandTransaction,
+  field,
+  from,
+  getEdgeWrites,
+  getEntityWrites,
+  getImplicitKeyFields,
+  gsi,
+  gsiAmbiguityRule,
+  hasMany,
+  hasOne,
+  hydrate,
+  isColumn,
+  isCommandBatchMode,
+  isCommandModelContract,
+  isCommandPlan,
+  isContractComposeNode,
+  isContractFromRef,
+  isContractKeyFieldRef,
+  isContractKeyRef,
+  isContractParamRef,
+  isEdgeWritesDefinition,
+  isEntityWritesDefinition,
+  isKeySegment,
+  isLifecycleContract,
+  isMutationFragment,
+  isMutationInputRef,
+  isParam,
+  isPlannedCommandMethod,
+  isQueryModelContract,
+  isSelectBuilder,
+  isTransactionRef,
+  k,
+  key,
+  lifecyclePhaseForIntent,
+  list,
+  literal,
+  map,
+  mintContractKeyFieldRef,
+  mintContractParamRef,
+  missingGsiRule,
+  model,
+  mutation,
+  noScanRule,
+  number,
+  numberSet,
+  param,
+  plan,
+  point,
+  publicCommandModel,
+  publicQueryModel,
+  query,
+  queryBoundaryRule,
+  range,
+  relationDepthRule,
+  requireLimitRule,
+  resolveKey,
+  resolveLifecycle,
+  resolveRelations,
+  serializeContractKey,
+  serializeFieldValue,
+  string,
+  stringSet,
+  validateDepth,
+  validateGsiAmbiguity,
+  when,
+  wholeKeysSentinel
+};