graphddb 0.7.9 → 0.8.0

package/dist/index.js

@@ -1,179 +1,83 @@
 import {
-  queryBoundaryRule
-} from "./chunk-MMVHOUM4.js";
-import {
-  BatchGetResult,
   DDBModel,
-  EDGE_WRITES_MARKER,
-  LOGICAL_EFFECT_CATEGORIES,
-  MARKER_ROW_ENTITY,
-  OLD_VALUE_NAMESPACE,
-  PREPARED_FORMAT_VERSION,
-  PREPARE_CACHE_MAX,
-  PreparedReadStatement,
-  PreparedWriteStatement,
-  RELATION_TRAVERSAL_CONCURRENCY,
-  SPEC_VERSION,
-  assertBundleSerializable,
-  assertContractBoundaries,
-  assertContractN1Safe,
-  assertJsonSerializable,
-  assertSupportedCondition,
-  buildBridgeBundle,
-  buildContexts,
-  buildContracts,
-  buildManifest,
-  buildManifestEntity,
-  buildOperations,
-  buildProjection,
-  buildQuerySpec,
-  buildTransactionSpec,
-  buildTransactions,
-  collectContractBoundaryViolations,
-  collectContractN1Violations,
-  compileFilterExpression,
-  compileFragment,
-  compileMutationPlan,
-  compileSingleFragmentPlan,
-  conditionParamName,
-  contractOfMethodSpec,
-  decodeCursor,
-  definePlan,
-  defineTransaction,
-  defineTransactions,
-  deriveCompositionPlan,
-  deriveEdgeWriteItems,
-  deriveEdgeWriteItemsFor,
-  deriveModelEdgeWriteItems,
-  edgeWrites,
-  encodeCursor,
-  entityFingerprint,
-  evaluateFilter,
-  execute,
-  executeBatchGet,
-  executeBatchWrite,
-  executeCommandMethod,
-  executeExplain,
-  executeList,
-  executeListInternal,
-  executeLogicalParallelWrites,
-  executeLogicalWriteOps,
-  executeQuery,
-  from,
-  getEdgeWrites,
-  isCommandModelContract,
-  isCommandPlan,
-  isContractComposeNode,
-  isContractFromRef,
-  isContractKeyFieldRef,
-  isContractKeyRef,
-  isContractParamRef,
-  isEdgeWritesDefinition,
-  isMutationFragment,
-  isMutationInputRef,
-  isPlannedCommandMethod,
-  isPreparedParamRef,
-  isQueryModelContract,
-  isTransactionRef,
-  mapWithConcurrency,
-  mintContractKeyFieldRef,
-  mintContractParamRef,
-  mutation,
-  plan,
-  prepare,
-  publicCommandModel,
-  publicQueryModel,
-  query,
-  resolveLifecycle,
-  resolveRelations,
-  serializeEffectParams,
-  validateDepth,
-  when,
-  wholeKeysSentinel
-} from "./chunk-NYM7K2ST.js";
+  mutate,
+  publishCommand,
+  publishQuery
+} from "./chunk-I4LEJ4TF.js";
 import {
-  CdcEmulator,
-  MAINT_OUTBOX_PK_PREFIX,
-  MaintenanceDrain,
-  compareDesc,
-  createCdcEmulator,
-  createMaintenanceDrain,
-  createMaintenanceDrainHandler,
-  orderAndTrimCollection,
-  pathField,
-  projectFrom
-} from "./chunk-ZPNRLOKA.js";
+  entityWrites,
+  getEntityWrites,
+  identity,
+  preview
+} from "./chunk-HNY2EJPV.js";
+import {
+  when
+} from "./chunk-L4QRCHRQ.js";
 import {
-  BATCH_GET_MAX_KEYS,
-  BATCH_WRITE_MAX_ITEMS,
   ClientManager,
-  DEFAULT_MAX_ATTEMPTS,
-  DEFAULT_RETRY_POLICY,
-  DynamoExecutor,
-  ENTITY_WRITES_MARKER,
-  LIFECYCLE_CONTRACT_MARKER,
-  MAX_TRANSACT_ITEMS,
   MetadataRegistry,
-  RetryingExecutor,
-  TransactionContext,
-  attachModelClass,
-  buildConditionExpression,
-  buildDeleteInput,
-  buildMaintenanceGraph,
-  buildPutInput,
-  buildSubscribeHandler,
-  buildUpdateExpression,
-  buildUpdateInput,
-  collapseSameKeyItems,
-  collectRawConditionParams,
-  collectViewDefinitions,
-  commitTransaction,
   cond,
-  detectRelationFields,
-  entityWrites,
-  execItemKeySignature,
-  executeDelete,
-  executePut,
-  executeTransaction,
-  executeUpdate,
-  getEntityWrites,
-  getImplicitKeyFields,
   gsi,
-  hydrate,
-  identity,
-  isEntityWritesDefinition,
-  isLifecycleContract,
-  isMaintainTrigger,
-  isParam,
-  isRawCondition,
-  isRetryableError,
-  isRetryableTransactionCancellation,
-  isSelectBuilder,
-  lifecyclePhaseForIntent,
-  maintainTrigger,
-  param,
-  parseChange,
-  preview,
-  resolveConditionTree,
-  resolveModelClass,
-  serializeFieldValue
-} from "./chunk-PFFPLD4B.js";
+  param
+} from "./chunk-L2NEDS7U.js";
 import {
-  Linter,
   TableMapping,
-  createDefaultLinter,
-  gsiAmbiguityRule,
-  isColumn,
-  isKeySegment,
   k,
-  key,
-  missingGsiRule,
-  noScanRule,
-  relationDepthRule,
-  requireLimitRule,
-  resolveKey,
-  segmentFieldNames
-} from "./chunk-PDUVTYC5.js";
+  key
+} from "./chunk-XTWXMOHD.js";
+
+// src/config/index.ts
+var config = {
+  /**
+   * Register the `DynamoDBClient` GraphDDB sends through.
+   *
+   * IMPORTANT (issue #111): GraphDDB owns single-op throttle / transient-error
+   * retry (see {@link config.retry}), so a client left at the AWS SDK default
+   * `maxAttempts: 3` retries MULTIPLICATIVELY underneath the library. Construct the
+   * client with `maxAttempts: 1` so the library is the single source of truth for
+   * retry — e.g. `graphddb.config.client(new DynamoDBClient({ maxAttempts: 1 }))`.
+   * GraphDDB does NOT mutate a client you pass in.
+   */
+  client(client) {
+    ClientManager.setClient(client);
+  },
+  /**
+   * Read back the registered `DynamoDBClient` — the resolved client last passed to
+   * {@link config.client}. Throws a clear error if no client has been registered
+   * yet (call {@link config.client} first).
+   */
+  getClient() {
+    return ClientManager.getClient();
+  },
+  /** Set the declared-model-name → physical-DynamoDB-table-name map. */
+  tables(mapping) {
+    TableMapping.set(mapping);
+  },
+  /**
+   * Configure the global single-op retry policy (issue #111) — exponential backoff
+   * + jitter with a bounded attempt cap, applied to every GetItem / Query / Put /
+   * Update / Delete / relation-fan-out send and to `TransactWriteItems`. A sensible
+   * default is ALWAYS on; call this only to tune it (or pass `null` to restore the
+   * default). A per-call `retry?: RetryPolicy | false` on an operation's options
+   * overrides this globally for that call (`false` disables retry).
+   */
+  retry(policy) {
+    ClientManager.setRetryPolicy(policy);
+  },
+  /**
+   * Register a {@link Middleware} (issue #50; read path #138, write path #139).
+   * One registered object may carry read and/or write hooks. Ordering: `before*`
+   * runs first-registered-first (FIFO); `after*` / `onError` run
+   * last-registered-first (LIFO). A host-runtime global; never serialized.
+   */
+  use(mw) {
+    ClientManager.use(mw);
+  },
+  /** Remove every registered middleware (read AND write; teardown / tests). See {@link config.use}. */
+  clearMiddleware() {
+    ClientManager.clearMiddleware();
+  }
+};
 
 // src/metadata/prefix.ts
 function derivePrefix(customPrefix, className) {
@@ -189,36 +93,6 @@ function derivePrefix(customPrefix, 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 = [];
@@ -533,7 +407,7 @@ function refs(targetFactory, options) {
         `@refs relation '${propertyName}': options must supply \`from\` (the parent list attribute, e.g. 'tagRefs') and \`key\` (the ref field on each element, e.g. 'tagId').`
       );
     }
-    const { from: from2, key: key2, to, ...relationOptions } = options;
+    const { from, key: key2, to, ...relationOptions } = options;
     const targetKeyField = to ?? key2;
     collectRelation({
       type: "refs",
@@ -542,7 +416,7 @@ function refs(targetFactory, options) {
       // Scalar keyBinding: target child key field ← element key name. Per resolved
       // element the existing scalar key-building machinery reuses this unchanged.
       keyBinding: { [targetKeyField]: key2 },
-      refs: { from: from2, key: key2 },
+      refs: { from, key: key2 },
       ...Object.keys(relationOptions).length > 0 ? { options: relationOptions } : {}
     });
   };
@@ -742,1622 +616,70 @@ function cdcProjected() {
   };
 }
 
-// src/operations/declarative-transaction.ts
-import { renderTemplate, TemplateFailure } from "behavior-contracts";
-
-// src/runtime/behavior-contracts-adapter.ts
-function toSharedValue(v) {
-  if (v === null || v === void 0) return null;
-  switch (typeof v) {
-    case "string":
-    case "boolean":
-    case "bigint":
-      return v;
-    case "number":
-      return Number.isInteger(v) ? BigInt(v) : v;
-    default:
-      break;
-  }
-  if (v instanceof Date) return v.toJSON();
-  if (Array.isArray(v)) return v.map((e) => toSharedValue(e));
-  if (typeof v === "object") {
-    const out = {};
-    for (const [k2, field2] of Object.entries(v)) {
-      if (field2 === void 0) continue;
-      out[k2] = toSharedValue(field2);
-    }
-    return out;
-  }
-  return v;
-}
-function toSharedParams(params) {
-  const out = {};
-  for (const [name, value] of Object.entries(params)) {
-    if (value === void 0) continue;
-    out[name] = toSharedValue(value);
-  }
-  return out;
-}
-
-// src/operations/declarative-transaction.ts
-var PLACEHOLDER_RE = /\{[^{}]+\}/g;
-function hasNonCoreScope(template) {
-  return (template.match(PLACEHOLDER_RE) ?? []).some((m) => {
-    const name = m.slice(1, -1);
-    return name.startsWith("item.") || name.startsWith("result.");
-  });
-}
-function resolveTemplate(template, params, element) {
-  if (hasNonCoreScope(template)) {
-    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]);
-    });
-  }
-  try {
-    return renderTemplate(template, toSharedParams(params));
-  } catch (exc) {
-    if (exc instanceof TemplateFailure && exc.code === "UNBOUND_PARAM") {
-      throw new Error(`declarative transaction: ${exc.message}.`);
-    }
-    throw exc;
-  }
-}
-function isWholePlaceholder(template) {
-  return /^\{[^{}]+\}$/.test(template);
-}
-function resolveValue(template, params, element) {
-  if (typeof template !== "string") return template;
-  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 resolveRawConditionValue(val, params, element) {
-  if (val !== null && typeof val === "object" && typeof val.$param === "string") {
-    return resolveValue(`{${val.$param}}`, params, element);
-  }
-  return val;
-}
-function applyCondition(condition, target, params, element) {
-  if (!condition) return;
-  const names = target.ExpressionAttributeNames ??= {};
-  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 ??= {};
-  if (condition.kind === "raw") {
-    Object.assign(names, condition.names);
-    for (const [alias, val] of Object.entries(condition.values)) {
-      values[alias] = resolveRawConditionValue(val, params, element);
-    }
-    target.ConditionExpression = condition.expression;
-    return;
-  }
-  if (condition.kind === "expr") {
-    const concrete = resolveConditionTree(
-      condition.declarative,
-      (name) => resolveValue(`{${name}}`, params, element)
-    );
-    const compiled = buildConditionExpression(concrete);
-    Object.assign(names, compiled.names);
-    Object.assign(values, compiled.values);
-    target.ConditionExpression = compiled.expression;
-    return;
-  }
-  const clauses = [];
-  let i = 0;
-  for (const [field2, tmpl] of Object.entries(condition.fields)) {
-    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 applyMaintainTransform(op, args, value) {
-  if (op === "identity") return value;
-  if (op === "preview") {
-    const n = args[0];
-    if (typeof n !== "number" || !Number.isInteger(n) || n <= 0) {
-      throw new Error(
-        `declarative transaction: a maintenance \`preview\` projection has a non-positive-integer length bound (${JSON.stringify(n)}).`
-      );
-    }
-    if (value === null || value === void 0) return value;
-    return String(value).slice(0, n);
-  }
-  throw new Error(
-    `declarative transaction: unknown maintenance projection op '${String(op)}' (expected 'identity' / 'preview').`
-  );
-}
-function buildMaintainProjection(maintain, params, element) {
-  const out = {};
-  for (const [attr, transform] of Object.entries(maintain.projection)) {
-    const value = resolveValue(`{${transform.inputField}}`, params, element);
-    out[attr] = applyMaintainTransform(transform.op, transform.args, value);
-  }
-  return out;
-}
-function buildMaintainUpdateItem(spec, maintain, table, key2, params, element) {
-  const update = { TableName: table, Key: key2 };
-  if (maintain.kind === "counter") {
-    const counter = maintain.counter;
-    if (counter === void 0) {
-      throw new Error(
-        `declarative transaction: a 'counter' maintenance write on '${spec.entity}' has no \`counter\` payload.`
-      );
-    }
-    update.UpdateExpression = "ADD #a0 :a0";
-    update.ExpressionAttributeNames = { "#a0": counter.attribute };
-    update.ExpressionAttributeValues = {
-      ":a0": typeof counter.delta === "string" ? Number(counter.delta) : counter.delta
-    };
-    return { Update: update };
-  }
-  const projection = buildMaintainProjection(maintain, params, element);
-  if (maintain.kind === "collection") {
-    const field2 = maintain.collection?.field;
-    if (field2 === void 0) {
-      throw new Error(
-        `declarative transaction: a 'collection' maintenance write on '${spec.entity}' has no \`collection.field\`.`
-      );
-    }
-    update.UpdateExpression = "SET #c = list_append(if_not_exists(#c, :empty), :item)";
-    update.ExpressionAttributeNames = { "#c": field2 };
-    update.ExpressionAttributeValues = { ":empty": [], ":item": [projection] };
-  } else {
-    const names = {};
-    const values = {};
-    const sets = [];
-    let i = 0;
-    for (const [attr, value] of Object.entries(projection)) {
-      names[`#m${i}`] = attr;
-      values[`:m${i}`] = value;
-      sets.push(`#m${i} = :m${i}`);
-      i++;
-    }
-    if (sets.length === 0) {
-      throw new Error(
-        `declarative transaction: a 'snapshot' maintenance write on '${spec.entity}' has an empty projection.`
-      );
-    }
-    update.UpdateExpression = `SET ${sets.join(", ")}`;
-    update.ExpressionAttributeNames = names;
-    update.ExpressionAttributeValues = values;
-  }
-  return { Update: update };
-}
-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 };
-  }
-  if (spec.maintain !== void 0) {
-    return buildMaintainUpdateItem(spec, spec.maintain, table, key2, params, element);
-  }
-  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: (count2) => new Error(
-        `declarative transaction: expanded to ${count2} items, exceeds the DynamoDB TransactWriteItems limit of ${MAX_TRANSACT_ITEMS}.`
-      )
-    }
-  );
-}
-
-// src/runtime/per-key-cursor.ts
-import { canonicalValue } from "behavior-contracts";
-function serializeContractKey(key2) {
-  return canonicalValue(toSharedValue(key2));
-}
-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, 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/prepared-loader.ts
-import { validateEnvelope, EnvelopeFailure } from "behavior-contracts";
-var LOAD_LABEL = "graphddb.loadPreparedPlan";
-function slotOfBind(bind) {
-  if ("param" in bind) return { kind: "param", name: bind.param };
-  if ("literal" in bind) return { kind: "literal", value: bind.literal };
-  if ("literalDate" in bind) return { kind: "literal", value: new Date(bind.literalDate) };
-  return { kind: "literal", value: BigInt(bind.literalBigInt) };
-}
-function slotsOfBindMap(map2) {
-  const out = {};
-  for (const [field2, bind] of Object.entries(map2 ?? {})) out[field2] = slotOfBind(bind);
-  return out;
-}
-function bindValues(slots, params) {
-  const out = {};
-  for (const [field2, slot] of Object.entries(slots)) {
-    out[field2] = slot.kind === "param" ? params[slot.name] : slot.value;
-  }
-  return out;
-}
-function resolveModelByName(name, planId) {
-  for (const modelClass of MetadataRegistry.getAll().keys()) {
-    if (modelClass.name === name) return modelClass;
-  }
-  throw new Error(
-    `${LOAD_LABEL}: static plan '${planId}' targets entity '${name}', which is not a registered model in this process. Ensure the model module is imported before the plan executes, or regenerate the artifact (graphddb transform prepared --aot).`
-  );
-}
-function bindEntities(plan2, planId) {
-  const classes = /* @__PURE__ */ new Map();
-  const entities = {};
-  const tables = {};
-  for (const [name, expected] of Object.entries(plan2.entities)) {
-    const modelClass = resolveModelByName(name, planId);
-    const metadata = MetadataRegistry.get(modelClass);
-    const actual = entityFingerprint(metadata);
-    if (actual !== expected) {
-      throw new Error(
-        `${LOAD_LABEL}: static plan '${planId}' is STALE \u2014 entity '${name}' has changed since the plan artifact was generated (declaration fingerprint mismatch: expected ${expected}, live ${actual}). A stale static plan never executes. Regenerate the artifact: \`graphddb transform prepared --aot <artifact> --write\` (CI: run the check mode to catch this at build time).`
-      );
-    }
-    classes.set(name, modelClass);
-    const entity = buildManifestEntity(metadata);
-    entities[name] = entity;
-    tables[metadata.tableName] = { physicalName: TableMapping.resolve(metadata.tableName) };
-  }
-  return { classes, manifest: { version: SPEC_VERSION, tables, entities } };
-}
-function renderSpecItem(transaction, index, manifest, params) {
-  const single = {
-    params: transaction.params,
-    items: [transaction.items[index]]
-  };
-  return expandTransactionItems(single, manifest, params);
-}
-function renderEffectsForOp(op, boundParams) {
-  const rendered = serializeEffectParams([op.modelClass], boundParams);
-  const effects = {};
-  const checks = [];
-  const modelBySignature = /* @__PURE__ */ new Map();
-  const { transaction, categories } = op.spec;
-  for (let i = 0; i < transaction.items.length; i++) {
-    const category = categories[i];
-    if (category === "base") continue;
-    for (const out of renderSpecItem(transaction, i, op.manifest, rendered)) {
-      const item = out.item;
-      if (category === "check") {
-        if (item.ConditionCheck !== void 0) checks.push(item.ConditionCheck);
-        continue;
-      }
-      const family = category;
-      if (!LOGICAL_EFFECT_CATEGORIES.includes(family)) {
-        throw new Error(
-          `${LOAD_LABEL}: unknown effect category '${String(category)}' in a static plan (artifact format skew \u2014 regenerate the artifact).`
-        );
-      }
-      (effects[family] ??= []).push(item);
-      if (out.model !== void 0) {
-        modelBySignature.set(execItemKeySignature(item), out.model);
-      }
-    }
-  }
-  return { effects, checks, modelBySignature };
-}
-var INTENT_TO_KIND = { create: "put", update: "update", remove: "delete" };
-var AotPreparedWriteStatement = class {
-  /** @internal */
-  constructor(ops) {
-    this.ops = ops;
-  }
-  ops;
-  async execute(params = {}, options = {}) {
-    const logical = this.ops.map((op) => {
-      const bound = {
-        ...bindValues(op.inputSlots, params),
-        ...bindValues(op.keySlots, params)
-      };
-      const condition = op.conditionSlots !== void 0 ? bindValues(op.conditionSlots, params) : void 0;
-      return {
-        kind: INTENT_TO_KIND[op.spec.intent],
-        modelClass: op.modelClass,
-        modelStatic: op.modelStatic,
-        keyFields: op.spec.keyFields,
-        params: bound,
-        // A `create` guards with attribute_not_exists — the same condition the
-        // compiled base op carries; an explicit gate on a create was rejected at
-        // BUILD time (mirroring the compiled core's `withCondition` reject).
-        ...op.spec.intent === "create" ? { condition: { notExists: true } } : condition !== void 0 ? { condition } : {},
-        ...op.spec.result !== void 0 ? { result: op.spec.result } : {},
-        renderEffects: (postW1) => renderEffectsForOp(op, postW1)
-      };
-    });
-    const mode = options.mode ?? "transaction";
-    const runOpts = {
-      label: LOAD_LABEL,
-      ...options.retry !== void 0 ? { retry: options.retry } : {},
-      ...options.context !== void 0 ? { context: options.context } : {}
-    };
-    if (mode === "transaction") {
-      const { readBacks } = await executeLogicalWriteOps(logical, runOpts);
-      const out2 = {};
-      this.ops.forEach((op, i) => {
-        if (op.spec.result !== void 0) out2[op.alias] = readBacks[i];
-      });
-      return out2;
-    }
-    const settled = await executeLogicalParallelWrites(logical, runOpts);
-    const out = {};
-    this.ops.forEach((op, i) => {
-      const res = settled[i];
-      out[op.alias] = res.ok ? { ok: true, value: op.spec.result !== void 0 ? res.value : void 0 } : { ok: false, error: res.error };
-    });
-    return out;
-  }
-};
-function bindReadPlan(plan2, planId) {
-  const { classes } = bindEntities(plan2, planId);
-  const routes = (plan2.reads ?? []).map((r) => {
-    const modelClass = classes.get(r.entity);
-    if (modelClass === void 0) {
-      throw new Error(
-        `${LOAD_LABEL}: static plan '${planId}' route '${r.alias}' targets entity '${r.entity}', which the plan does not fingerprint (artifact skew \u2014 regenerate).`
-      );
-    }
-    const consistentReadSlot = r.consistentRead !== void 0 ? slotOfBind(r.consistentRead) : void 0;
-    const limitSlot = r.limit !== void 0 ? slotOfBind(r.limit) : void 0;
-    const afterSlot = r.after !== void 0 ? slotOfBind(r.after) : void 0;
-    return {
-      alias: r.alias,
-      kind: r.op,
-      modelClass,
-      select: r.select,
-      keySlots: slotsOfBindMap(r.key),
-      ...r.maxDepth !== void 0 ? { maxDepth: r.maxDepth } : {},
-      ...r.order !== void 0 ? { order: r.order } : {},
-      ...r.filter !== void 0 ? { filter: r.filter } : {},
-      ...consistentReadSlot !== void 0 ? { consistentReadSlot } : {},
-      ...limitSlot !== void 0 ? { limitSlot } : {},
-      ...afterSlot !== void 0 ? { afterSlot } : {}
-    };
-  });
-  return new PreparedReadStatement(routes);
-}
-function bindWritePlan(plan2, planId) {
-  const { classes, manifest } = bindEntities(plan2, planId);
-  const ops = (plan2.writes ?? []).map((w) => {
-    const modelClass = classes.get(w.entity);
-    if (modelClass === void 0) {
-      throw new Error(
-        `${LOAD_LABEL}: static plan '${planId}' op '${w.alias}' targets entity '${w.entity}', which the plan does not fingerprint (artifact skew \u2014 regenerate).`
-      );
-    }
-    const modelStatic = modelClass.asModel();
-    return {
-      alias: w.alias,
-      spec: w,
-      modelClass,
-      modelStatic,
-      keySlots: slotsOfBindMap(w.key),
-      inputSlots: slotsOfBindMap(w.input),
-      ...w.condition !== void 0 ? { conditionSlots: slotsOfBindMap(w.condition) } : {},
-      manifest
-    };
-  });
-  return new AotPreparedWriteStatement(ops);
-}
-function bindPlan(doc, planId) {
-  if (doc === null || typeof doc !== "object" || doc.plans === void 0) {
-    throw new Error(`${LOAD_LABEL}: not a prepared-plan document.`);
-  }
-  if (doc.formatVersion !== PREPARED_FORMAT_VERSION) {
-    if (doc.formatVersion === "1") {
-      throw new Error(
-        `${LOAD_LABEL}: this artifact uses prepared-plan format version '1' (generated by graphddb <= 0.7.2). This runtime speaks format '${PREPARED_FORMAT_VERSION}' (the entity fingerprints changed algorithm), so the artifact must be regenerated with the transform: \`graphddb transform prepared --aot <artifact> --write\`.`
-      );
-    }
-    throw new Error(
-      `${LOAD_LABEL}: unsupported artifact format version '${String(doc.formatVersion)}' (this runtime supports '${PREPARED_FORMAT_VERSION}'). Regenerate the artifact: \`graphddb transform prepared --aot <artifact> --write\`.`
-    );
-  }
-  try {
-    validateEnvelope(doc, SPEC_VERSION, { field: "specVersion", label: LOAD_LABEL });
-  } catch (exc) {
-    if (exc instanceof EnvelopeFailure) {
-      throw new Error(
-        `${LOAD_LABEL}: the artifact was compiled against operation-IR version '${String(doc.specVersion)}' but this runtime speaks '${SPEC_VERSION}'. A version-skewed static plan never executes \u2014 regenerate the artifact.`
-      );
-    }
-    throw exc;
-  }
-  const plan2 = doc.plans[planId];
-  if (plan2 === void 0) {
-    const available = Object.keys(doc.plans).sort().slice(0, 8).join(", ");
-    throw new Error(
-      `${LOAD_LABEL}: the artifact carries no plan '${planId}' (available: ${available}${Object.keys(doc.plans).length > 8 ? ", \u2026" : ""}). The source and the artifact have drifted \u2014 regenerate: \`graphddb transform prepared --aot <artifact> --write\`.`
-    );
-  }
-  return plan2.kind === "read" ? bindReadPlan(plan2, planId) : bindWritePlan(plan2, planId);
-}
-var BOUND = /* @__PURE__ */ new WeakMap();
-var LazyAotHandle = class {
-  constructor(doc, planId) {
-    this.doc = doc;
-    this.planId = planId;
-  }
-  doc;
-  planId;
-  bound;
-  resolve() {
-    if (this.bound !== void 0) return this.bound;
-    let perDoc = BOUND.get(this.doc);
-    if (perDoc === void 0) {
-      perDoc = /* @__PURE__ */ new Map();
-      BOUND.set(this.doc, perDoc);
-    }
-    let handle = perDoc.get(this.planId);
-    if (handle === void 0) {
-      handle = bindPlan(this.doc, this.planId);
-      perDoc.set(this.planId, handle);
-    }
-    this.bound = handle;
-    return handle;
-  }
-  async execute(params, options) {
-    const target = this.resolve();
-    return target.execute(params, options);
-  }
-};
-function loadPreparedPlan(doc, planId, body) {
-  void body;
-  return new LazyAotHandle(doc, planId);
-}
-
-// src/relation/maintenance-rebuild.ts
-function toClass(m) {
-  try {
-    return resolveModelClass(m);
-  } catch {
-    return m;
-  }
-}
-var MaintenanceRebuilder = class {
-  graph;
-  constructor(opts = {}) {
-    const classes = (opts.models ?? []).map(toClass);
-    const explicitViews = opts.views;
-    const allClasses = [
-      ...classes,
-      ...(explicitViews ?? []).map((v) => v.viewClass)
-    ];
-    const scoped = allClasses.length > 0 ? new Map(allClasses.map((c) => [c, MetadataRegistry.get(c)])) : void 0;
-    this.graph = buildMaintenanceGraph(scoped, explicitViews);
-  }
-  /**
-   * Re-derive the materialized value for one owner row × maintainer from the source
-   * rows and report whether it differs from what the owner row currently stores. Does
-   * NOT write anything (a read-only drift probe).
-   *
-   * @param owner The owner model class declaring the maintainer.
-   * @param relationProperty The relation / `@aggregate` property the value lives under.
-   * @param ownerKeyInput The owner row's key input (e.g. `{ threadId: 't1' }`).
-   */
-  async detectDrift(owner, relationProperty, ownerKeyInput) {
-    const { item, ownerMeta, ownerKey } = this.resolve(owner, relationProperty);
-    const expected = await this.recompute(item, ownerMeta, ownerKeyInput);
-    const ownerRow = await this.readOwnerRow(ownerMeta, ownerKey(ownerKeyInput));
-    const actual = this.actualValue(item.effect, ownerRow);
-    const ownerAbsentAndEmpty = ownerRow === void 0 && isEmptyMaintained(item.effect, expected);
-    return {
-      relationProperty,
-      ownerEntity: item.ownerEntity,
-      ownerKey: ownerKey(ownerKeyInput),
-      kind: item.effect.kind,
-      drifted: !ownerAbsentAndEmpty && !deepEqual(normalize(expected), normalize(actual)),
-      expected,
-      actual
-    };
-  }
-  /**
-   * Re-derive the materialized value for one owner row × maintainer from the source
-   * rows and WRITE the absolute re-derived value onto the owner row when it drifts (or
-   * always, when `force`). Returns the drift verdict plus whether a repair write ran.
-   *
-   * @param options.force Write even when no drift is detected (default: write only on drift).
-   */
-  async rebuild(owner, relationProperty, ownerKeyInput, options = {}) {
-    const report = await this.detectDrift(owner, relationProperty, ownerKeyInput);
-    if (!report.drifted && options.force !== true) {
-      return { ...report, repaired: false };
-    }
-    const { item, ownerMeta } = this.resolve(owner, relationProperty);
-    await this.writeValue(item.effect, ownerMeta, report.ownerKey, report.expected);
-    return { ...report, repaired: true };
-  }
-  /** Resolve an owner model + property to its {@link MaintainItem} + owner-key builder. */
-  resolve(owner, relationProperty) {
-    const ownerClass = toClass(owner);
-    const ownerMeta = MetadataRegistry.get(ownerClass);
-    const item = this.graph.items.find(
-      (i) => i.relationProperty === relationProperty && (i.ownerClass === ownerClass || i.ownerClass.name === ownerClass.name)
-    );
-    if (item === void 0) {
-      throw new Error(
-        `Maintenance rebuild: no maintainer found for property '${relationProperty}' on '${ownerClass.name}'. The rebuilder repairs declared \`maintainedOn\` maintainers (snapshot / collection / counter); '${relationProperty}' declares none, or its model is not in this rebuilder's scope.`
-      );
-    }
-    const ownerKey = (input) => {
-      const { Key } = buildDeleteInput(
-        ownerClass,
-        input
-      );
-      return Key;
-    };
-    return { item, ownerMeta, ownerKey };
-  }
-  /**
-   * Scan every source row bound to this owner row and re-derive the maintained value:
-   *
-   *  - **collection** — project each source row, order + trim by the SAME read-side
-   *    rules (`orderBy` / `orderDir` / `maxItems`) the drain uses, return the list;
-   *  - **snapshot** — project the single bound source row (or `undefined` when none);
-   *  - **counter `count`** — the COUNT of source rows (absolute, not an ADD);
-   *  - **counter `max`** — the maximum source value of the tracked field.
-   */
-  async recompute(item, _ownerMeta, ownerKeyInput) {
-    const effect = item.effect;
-    if (effect.kind === "membership") {
-      throw new Error(
-        `Maintenance rebuild: sparse-view membership maintainer '${item.relationProperty}' on '${item.ownerEntity}' is not yet supported by the rebuild planner (#133 follow-up). A membership row appears/disappears per source row by predicate; rebuild it by re-running the source events through the drain.`
-      );
-    }
-    const sources = await this.scanSourceRows(item, ownerKeyInput);
-    if (effect.kind === "collection") {
-      return this.recomputeCollection(effect, sources);
-    }
-    if (effect.kind === "snapshot") {
-      return this.recomputeSnapshot(effect, sources);
-    }
-    return this.recomputeCounter(effect, sources);
-  }
-  /**
-   * The source rows bound to one owner row. The maintenance key binding is
-   * `{ ownerField: '$.entity.<sourceField>' }` (the destination owner-key field ← the
-   * source row's field). INVERTED for a rebuild: the owner row supplies the value, and
-   * the source partition is queried for rows whose `<sourceField>` matches — exactly the
-   * set the live `hasMany` / `@aggregate` read aggregates. Queries the source via the
-   * same {@link plan} the read planner uses (a partition Query), paginating fully.
-   */
-  async scanSourceRows(item, ownerKeyInput) {
-    const sourceMeta = MetadataRegistry.get(item.sourceClass);
-    const queryKey = {};
-    for (const [ownerField, srcPath] of Object.entries(item.effect.keys)) {
-      const sourceField = pathField(srcPath);
-      queryKey[sourceField] = ownerKeyInput[ownerField];
-    }
-    const executor = ClientManager.getExecutor();
-    const rows = [];
-    let after;
-    do {
-      const execPlan = plan(sourceMeta, {
-        key: queryKey,
-        // Select all declared source fields so every projection / value source path
-        // and the sort-key leaf is present on the scanned row.
-        select: selectAll(sourceMeta),
-        consistentRead: false,
-        ...after ? { after } : {}
-      });
-      const op = execPlan.operations[0];
-      const res = await executor.execute(op);
-      for (const it of res.items) rows.push(it);
-      after = res.lastEvaluatedKey;
-    } while (after !== void 0);
-    return rows;
-  }
-  /** Re-derive a bounded collection: project, then order + trim by the read-side rules. */
-  recomputeCollection(effect, sources) {
-    if (effect.collection.orderBy === void 0 && effect.collection.maxItems !== void 0) {
-      throw new Error(
-        `Maintenance rebuild: relation '${effect.collection.field}' maintains an UNORDERED bounded collection (\`maxItems: ${effect.collection.maxItems}\` with no \`read.order\`). Its trimmed contents depend on stream ARRIVAL order, which the source rows do not record, so the value cannot be faithfully rebuilt from source \u2014 a rebuild would keep a different subset than the drain converged to. Declare a \`read.order\` on the relation so the maintained collection orders by the source's sort-key field (then the rebuild and the drain agree), or rebuild it unbounded.`
-      );
-    }
-    const projected = sources.map((row) => projectFrom(effect.project, row));
-    return orderAndTrimCollection(projected, effect.collection);
-  }
-  /**
-   * Re-derive a single-row snapshot. A snapshot mirrors ONE source row (a `belongsTo` /
-   * `hasOne`, normally 1:1). In the unusual case where MORE THAN ONE source row binds, the
-   * live single-value read takes the FIRST row in the source's natural query order
-   * (`ScanIndexForward`, default ASC = the smallest sort-key leaf), so re-derive the same
-   * row — {@link pickFirst} — for a verdict consistent with the live read. Returns
-   * `undefined` when no source row is bound (the snapshot should be absent).
-   */
-  recomputeSnapshot(effect, sources) {
-    if (sources.length === 0) return void 0;
-    const chosen = sources.length === 1 ? sources[0] : pickFirst(sources, this.sourceMetaOf(effect));
-    return projectFrom(effect.project, chosen);
-  }
-  /** The source entity metadata a maintain effect projects from (its relation target). */
-  sourceMetaOf(effect) {
-    const item = this.graph.items.find((i) => i.effect === effect);
-    return item ? MetadataRegistry.get(item.sourceClass) : void 0;
-  }
-  /** Re-derive a counter: the absolute COUNT of source rows, or the MAX of the tracked field. */
-  recomputeCounter(effect, sources) {
-    if (effect.value.op === "count") {
-      return sources.length;
-    }
-    const field2 = effect.value.field;
-    let best;
-    for (const row of sources) {
-      const v = row[field2];
-      if (v === void 0 || v === null) continue;
-      if (best === void 0 || compareDesc(v, best) < 0) best = v;
-    }
-    return best;
-  }
-  /** Read the owner row (consistent) for the drift comparison / actual value. */
-  async readOwnerRow(ownerMeta, ownerKey) {
-    const res = await ClientManager.getExecutor().execute({
-      type: "GetItem",
-      tableName: TableMapping.resolve(ownerMeta.tableName),
-      keyCondition: ownerKey,
-      consistentRead: true
-    });
-    return res.items[0];
-  }
-  /** The value currently stored on the owner row for this maintainer. */
-  actualValue(effect, ownerRow) {
-    if (ownerRow === void 0) return void 0;
-    if (effect.kind === "collection") {
-      return ownerRow[effect.collection.field];
-    }
-    if (effect.kind === "counter") {
-      return ownerRow[effect.attribute];
-    }
-    const out = {};
-    let anyPresent = false;
-    for (const attr of Object.keys(effect.project)) {
-      if (Object.prototype.hasOwnProperty.call(ownerRow, attr)) {
-        out[attr] = ownerRow[attr];
-        anyPresent = true;
-      }
-    }
-    return anyPresent ? out : void 0;
-  }
-  /** Write the re-derived ABSOLUTE value onto the owner row (the repair). */
-  async writeValue(effect, ownerMeta, ownerKey, expected) {
-    const TableName = TableMapping.resolve(ownerMeta.tableName);
-    const executor = ClientManager.getExecutor();
-    if (effect.kind === "collection") {
-      await executor.update({
-        TableName,
-        Key: ownerKey,
-        UpdateExpression: "SET #c = :list",
-        ExpressionAttributeNames: { "#c": effect.collection.field },
-        ExpressionAttributeValues: { ":list": expected ?? [] }
-      });
-      return;
-    }
-    if (effect.kind === "counter") {
-      if (expected === void 0 || expected === null) {
-        if (effect.value.op === "count") {
-          await executor.update({
-            TableName,
-            Key: ownerKey,
-            UpdateExpression: "SET #a = :v",
-            ExpressionAttributeNames: { "#a": effect.attribute },
-            ExpressionAttributeValues: { ":v": 0 }
-          });
-        } else {
-          await executor.update({
-            TableName,
-            Key: ownerKey,
-            UpdateExpression: "REMOVE #a",
-            ExpressionAttributeNames: { "#a": effect.attribute }
-          });
-        }
-        return;
-      }
-      await executor.update({
-        TableName,
-        Key: ownerKey,
-        UpdateExpression: "SET #a = :v",
-        ExpressionAttributeNames: { "#a": effect.attribute },
-        ExpressionAttributeValues: { ":v": expected }
-      });
-      return;
-    }
-    if (expected === void 0) {
-      const names2 = {};
-      const removes = [];
-      let i2 = 0;
-      for (const attr of Object.keys(effect.project)) {
-        names2[`#m${i2}`] = attr;
-        removes.push(`#m${i2}`);
-        i2 += 1;
-      }
-      if (removes.length === 0) return;
-      await executor.update({
-        TableName,
-        Key: ownerKey,
-        UpdateExpression: `REMOVE ${removes.join(", ")}`,
-        ExpressionAttributeNames: names2
-      });
-      return;
-    }
-    const projection = expected;
-    const names = {};
-    const values = {};
-    const sets = [];
-    let i = 0;
-    for (const [attr, value] of Object.entries(projection)) {
-      names[`#m${i}`] = attr;
-      values[`:m${i}`] = value;
-      sets.push(`#m${i} = :m${i}`);
-      i += 1;
-    }
-    if (sets.length === 0) return;
-    await executor.update({
-      TableName,
-      Key: ownerKey,
-      UpdateExpression: `SET ${sets.join(", ")}`,
-      ExpressionAttributeNames: names,
-      ExpressionAttributeValues: values
-    });
+// src/index.ts
+var graphddb = {
+  publishQuery,
+  publishCommand,
+  get query() {
+    return DDBModel.query;
+  },
+  get mutate() {
+    return DDBModel.mutate;
+  },
+  get prepare() {
+    return DDBModel.prepare;
+  },
+  get subscribe() {
+    return DDBModel.subscribe;
+  },
+  // ── Phase 4 S7 (#284): the host-runtime config surface. A LAZY getter for the
+  // same tree-shaking reason as the four execution verbs above — an eager
+  // `config: configImpl` reference would pin the `ClientManager` / executor /
+  // middleware impl graph into the size-limited core entry for a consumer that
+  // only imports `{ DDBModel }` and never touches `graphddb.config`. The getter
+  // defers the read so the config machinery is tree-shaken out of such a consumer
+  // and pulled in lazily by a real `graphddb.config.*` user. Do NOT revert this to
+  // an eager reference without re-checking `npm run size`.
+  get config() {
+    return config;
   }
 };
-function selectAll(meta) {
-  const select = {};
-  for (const f of meta.fields) select[f.propertyName] = true;
-  return select;
-}
-function pickFirst(sources, sourceMeta) {
-  const skFields = sourceMeta?.primaryKey ? segmentFieldNames(sourceMeta.primaryKey.segmented.skSegments) : [];
-  const orderField = skFields[skFields.length - 1];
-  if (orderField === void 0) return sources[0];
-  return [...sources].sort((a, b) => compareDesc(b[orderField], a[orderField]))[0];
-}
-function normalize(value) {
-  if (value === void 0 || value === null) return void 0;
-  if (typeof value === "number") return value;
-  if (typeof value === "string" && /^-?\d+$/.test(value)) {
-    const n = Number(value);
-    if (Number.isSafeInteger(n)) return n;
-  }
-  if (Array.isArray(value)) return value.map(normalize);
-  if (typeof value === "object") {
-    const out = {};
-    for (const [k2, v] of Object.entries(value)) {
-      const nv = normalize(v);
-      if (nv === void 0) continue;
-      out[k2] = nv;
-    }
-    return out;
-  }
-  return value;
-}
-function isEmptyMaintained(effect, expected) {
-  if (effect.kind === "collection") {
-    return Array.isArray(expected) && expected.length === 0;
-  }
-  if (effect.kind === "counter") {
-    return effect.value.op === "count" ? expected === 0 : expected === void 0 || expected === null;
-  }
-  return expected === void 0;
-}
-function deepEqual(a, b) {
-  if (a === b) return true;
-  if (a === void 0 || b === void 0 || a === null || b === null) return a === b;
-  if (Array.isArray(a) && Array.isArray(b)) {
-    if (a.length !== b.length) return false;
-    return a.every((v, i) => deepEqual(v, b[i]));
-  }
-  if (typeof a === "object" && typeof b === "object") {
-    const ka = Object.keys(a);
-    const kb = Object.keys(b);
-    if (ka.length !== kb.length) return false;
-    return ka.every(
-      (k2) => deepEqual(
-        a[k2],
-        b[k2]
-      )
-    );
-  }
-  return false;
-}
-function createMaintenanceRebuilder(opts = {}) {
-  return new MaintenanceRebuilder(opts);
-}
-
-// 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 = {
-    kind: value.kind,
-    ...value.literals !== void 0 ? { literals: value.literals } : {},
-    // Pure-documentation description (issue #154); carried through verbatim. Does
-    // not participate in the conflicting-kind check below (it is not part of the
-    // execution-relevant descriptor identity).
-    ...value.description !== void 0 ? { description: value.description } : {},
-    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;
-  if (isRawCondition(condition)) {
-    for (const { name, param: param2 } of collectRawConditionParams(condition)) {
-      out[name] = descriptorFromParam(name, param2, out[name]);
-    }
-    return;
-  }
-  const obj = condition;
-  if (obj.notExists === true) return;
-  if (typeof obj.attributeExists === "string") return;
-  if (typeof obj.attributeNotExists === "string") return;
-  collectConditionTreeParams(obj, out);
-}
-var SINGLE_OPERAND_OPS = /* @__PURE__ */ new Set([
-  "eq",
-  "ne",
-  "gt",
-  "ge",
-  "lt",
-  "le",
-  "beginsWith",
-  "contains",
-  "notContains",
-  "attributeType",
-  "size"
-]);
-function collectConditionTreeParams(obj, out) {
-  for (const [key2, value] of Object.entries(obj)) {
-    if (value === void 0) continue;
-    if (key2 === "and" || key2 === "or") {
-      for (const sub of value) {
-        if (isRawCondition(sub)) {
-          for (const { name, param: param2 } of collectRawConditionParams(sub)) {
-            out[name] = descriptorFromParam(name, param2, out[name]);
-          }
-          continue;
-        }
-        collectConditionTreeParams(sub, out);
-      }
-      continue;
-    }
-    if (key2 === "not") {
-      if (isRawCondition(value)) {
-        for (const { name, param: param2 } of collectRawConditionParams(value)) {
-          out[name] = descriptorFromParam(name, param2, out[name]);
-        }
-        continue;
-      }
-      collectConditionTreeParams(value, out);
-      continue;
-    }
-    if (isParam(value)) {
-      out[key2] = descriptorFromParam(key2, value, out[key2]);
-      continue;
-    }
-    if (value === null || typeof value !== "object" || value instanceof Date) {
-      continue;
-    }
-    const ops = value;
-    for (const [op, opVal] of Object.entries(ops)) {
-      if (op === "between") {
-        const [lo, hi] = opVal;
-        if (isParam(lo)) {
-          const n = conditionParamName(key2, op, 0);
-          out[n] = descriptorFromParam(n, lo, out[n]);
-        }
-        if (isParam(hi)) {
-          const n = conditionParamName(key2, op, 1);
-          out[n] = descriptorFromParam(n, hi, out[n]);
-        }
-      } else if (op === "in") {
-        opVal.forEach((v, i) => {
-          if (isParam(v)) {
-            const n = conditionParamName(key2, op, i);
-            out[n] = descriptorFromParam(n, v, out[n]);
-          }
-        });
-      } else if (SINGLE_OPERAND_OPS.has(op) && isParam(opVal)) {
-        const n = conditionParamName(key2, op);
-        out[n] = descriptorFromParam(n, opVal, out[n]);
-      }
-    }
-  }
-}
-function makeDefinition(model2, operation, key2, select, changes, condition, description) {
-  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 } : {},
-    ...description !== void 0 ? { description } : {},
-    params
-  };
-}
-function defineQuery(model2, key2, select, options) {
-  return makeDefinition(
-    model2,
-    "query",
-    key2,
-    select,
-    void 0,
-    void 0,
-    options?.description
-  );
-}
-function defineList(model2, key2, select, options) {
-  return makeDefinition(
-    model2,
-    "list",
-    key2,
-    select,
-    void 0,
-    void 0,
-    options?.description
-  );
-}
-function definePut(model2, item, options) {
-  return makeDefinition(
-    model2,
-    "put",
-    item,
-    void 0,
-    void 0,
-    options?.condition,
-    options?.description
-  );
-}
-function defineUpdate(model2, key2, changes, options) {
-  return makeDefinition(
-    model2,
-    "update",
-    key2,
-    void 0,
-    changes,
-    options?.condition,
-    options?.description
-  );
-}
-function defineDelete(model2, key2, options) {
-  return makeDefinition(
-    model2,
-    "delete",
-    key2,
-    void 0,
-    void 0,
-    options?.condition,
-    options?.description
-  );
-}
-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 {
-  AotPreparedWriteStatement,
-  BATCH_GET_MAX_KEYS,
-  BATCH_WRITE_MAX_ITEMS,
-  BatchGetResult,
-  CONTRACT_RANGE_FANOUT_CONCURRENCY,
-  CdcEmulator,
-  ClientManager,
   DDBModel,
-  DEFAULT_MAX_ATTEMPTS,
-  DEFAULT_RETRY_POLICY,
-  DynamoExecutor,
-  EDGE_WRITES_MARKER,
-  ENTITY_WRITES_MARKER,
-  LIFECYCLE_CONTRACT_MARKER,
-  Linter,
-  MAINT_OUTBOX_PK_PREFIX,
-  MAX_TRANSACT_ITEMS,
-  MaintenanceDrain,
-  MaintenanceRebuilder,
-  MetadataRegistry,
-  OLD_VALUE_NAMESPACE,
-  PREPARE_CACHE_MAX,
-  PreparedReadStatement,
-  PreparedWriteStatement,
-  RetryingExecutor,
-  SPEC_VERSION,
-  TableMapping,
-  TransactionContext,
   aggregate,
-  assertBundleSerializable,
-  assertContractBoundaries,
-  assertContractN1Safe,
-  assertJsonSerializable,
-  assertSupportedCondition,
-  attachModelClass,
   belongsTo,
   binary,
   boolean,
-  buildBridgeBundle,
-  buildConditionExpression,
-  buildContexts,
-  buildContracts,
-  buildDeleteInput,
-  buildMaintenanceGraph,
-  buildManifest,
-  buildOperations,
-  buildProjection,
-  buildPutInput,
-  buildQuerySpec,
-  buildSubscribeHandler,
-  buildTransactionSpec,
-  buildTransactions,
-  buildUpdateExpression,
-  buildUpdateInput,
   cdcProjected,
-  collectContractBoundaryViolations,
-  collectContractN1Violations,
-  collectViewDefinitions,
-  compileFilterExpression,
-  compileFragment,
-  compileMutationPlan,
-  compileSingleFragmentPlan,
   cond,
-  contractOfMethodSpec,
   count,
-  createCdcEmulator,
-  createDefaultLinter,
-  createMaintenanceDrain,
-  createMaintenanceDrainHandler,
-  createMaintenanceRebuilder,
   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,
+  graphddb,
   gsi,
-  gsiAmbiguityRule,
   hasMany,
   hasOne,
-  hydrate,
   identity,
-  isColumn,
-  isCommandModelContract,
-  isCommandPlan,
-  isContractComposeNode,
-  isContractFromRef,
-  isContractKeyFieldRef,
-  isContractKeyRef,
-  isContractParamRef,
-  isEdgeWritesDefinition,
-  isEntityWritesDefinition,
-  isKeySegment,
-  isLifecycleContract,
-  isMaintainTrigger,
-  isMutationFragment,
-  isMutationInputRef,
-  isParam,
-  isPlannedCommandMethod,
-  isPreparedParamRef,
-  isQueryModelContract,
-  isRetryableError,
-  isRetryableTransactionCancellation,
-  isSelectBuilder,
-  isTransactionRef,
   k,
   key,
-  lifecyclePhaseForIntent,
   list,
   literal,
-  loadPreparedPlan,
-  maintainTrigger,
   maintainedFrom,
   map,
   max,
-  mintContractKeyFieldRef,
-  mintContractParamRef,
-  missingGsiRule,
   model,
-  mutation,
-  noScanRule,
+  mutate,
   number,
   numberSet,
   param,
-  parseChange,
-  plan,
-  prepare,
   preview,
-  publicCommandModel,
-  publicQueryModel,
-  query,
-  queryBoundaryRule,
   refs,
-  relationDepthRule,
-  requireLimitRule,
-  resolveKey,
-  resolveLifecycle,
-  resolveRelations,
-  serializeContractKey,
-  serializeFieldValue,
   string,
   stringSet,
   ttl,
-  validateDepth,
-  validateGsiAmbiguity,
   when,
-  whenMember,
-  wholeKeysSentinel
+  whenMember
 };