graphddb 0.1.0

package/dist/chunk-347U24SB.js

@@ -0,0 +1,1818 @@
+// src/select/column.ts
+var COLUMN_REF = /* @__PURE__ */ Symbol.for("graphddb.columnRef");
+function isColumn(value) {
+  return typeof value === "object" && value !== null && value[COLUMN_REF] === true;
+}
+function createColumnMap() {
+  const cache = /* @__PURE__ */ new Map();
+  return new Proxy(
+    {},
+    {
+      get(_target, prop) {
+        if (typeof prop !== "string") return void 0;
+        let col = cache.get(prop);
+        if (!col) {
+          col = { [COLUMN_REF]: true, name: prop };
+          cache.set(prop, col);
+        }
+        return col;
+      }
+    }
+  );
+}
+
+// src/decorators/key.ts
+var KEY_MARKER = /* @__PURE__ */ Symbol("graphddb:key");
+var KEY_SEGMENT = /* @__PURE__ */ Symbol("graphddb:keySegment");
+function isKeySegment(value) {
+  return typeof value === "object" && value !== null && value[KEY_SEGMENT] === true;
+}
+function k(literals, ...columns) {
+  for (let i = 0; i < columns.length; i++) {
+    if (!isColumn(columns[i])) {
+      throw new Error(
+        `k\`...\`: interpolation #${i} must be a typed column reference (e.g. \`c.userId\`), not ${typeof columns[i]}. Key segments name fields via column references so they stay type-safe.`
+      );
+    }
+  }
+  return {
+    [KEY_SEGMENT]: true,
+    literals: [...literals],
+    columns
+  };
+}
+function isKeyDefinition(value) {
+  return typeof value === "object" && value !== null && KEY_MARKER in value;
+}
+function normalizeSegments(spec) {
+  if (spec === void 0) return [];
+  const list = Array.isArray(spec) ? spec : [spec];
+  for (const seg of list) {
+    if (!isKeySegment(seg)) {
+      throw new Error(
+        "key()/gsi(): pk and sk must be built with the `k` tagged template (e.g. k`USER#${c.userId}`) or an array of them."
+      );
+    }
+  }
+  return list;
+}
+function segmentFieldNames(segments) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const seg of segments) {
+    for (const col of seg.columns) {
+      if (!seen.has(col.name)) {
+        seen.add(col.name);
+        out.push(col.name);
+      }
+    }
+  }
+  return out;
+}
+function buildSegmentedKey(structure) {
+  const pkSegments = normalizeSegments(structure.pk);
+  const skSegments = normalizeSegments(structure.sk);
+  if (pkSegments.length === 0) {
+    throw new Error("key()/gsi(): pk must define at least one segment.");
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const inputFieldNames = [];
+  for (const name of [
+    ...segmentFieldNames(pkSegments),
+    ...segmentFieldNames(skSegments)
+  ]) {
+    if (!seen.has(name)) {
+      seen.add(name);
+      inputFieldNames.push(name);
+    }
+  }
+  return { segmented: { pkSegments, skSegments }, inputFieldNames };
+}
+function key(builder) {
+  const accessor = createColumnMap();
+  const structure = builder(accessor);
+  const { segmented, inputFieldNames } = buildSegmentedKey(structure);
+  return {
+    [KEY_MARKER]: true,
+    segmented,
+    inputFieldNames
+  };
+}
+
+// src/decorators/gsi.ts
+var GSI_MARKER = /* @__PURE__ */ Symbol("graphddb:gsi");
+function isGsiDefinition(value) {
+  return typeof value === "object" && value !== null && GSI_MARKER in value;
+}
+function gsi(indexName, builder, options) {
+  const accessor = createColumnMap();
+  const structure = builder(accessor);
+  const { segmented, inputFieldNames } = buildSegmentedKey(structure);
+  return {
+    [GSI_MARKER]: true,
+    indexName,
+    segmented,
+    inputFieldNames,
+    unique: options?.unique ?? false
+  };
+}
+
+// src/linter/linter.ts
+var Linter = class {
+  rules = [];
+  addRule(rule) {
+    this.rules.push(rule);
+  }
+  run(metadata, registry) {
+    const results = [];
+    for (const rule of this.rules) {
+      results.push(...rule.check(metadata, registry));
+    }
+    return results;
+  }
+  runAll(registry) {
+    const results = [];
+    const all = registry.getAll();
+    for (const [, metadata] of all) {
+      results.push(...this.run(metadata, registry));
+    }
+    return results;
+  }
+};
+
+// src/linter/rules/no-scan.ts
+var noScanRule = {
+  id: "no-scan",
+  severity: "error",
+  check(metadata) {
+    if (metadata.primaryKey === null && metadata.gsiDefinitions.length === 0) {
+      return [
+        {
+          ruleId: "no-scan",
+          severity: "error",
+          message: `Entity '${metadata.prefix}' has no primaryKey or GSI defined. All reads would require a full table scan.`,
+          entity: metadata.prefix
+        }
+      ];
+    }
+    return [];
+  }
+};
+
+// src/linter/rules/require-limit.ts
+var requireLimitRule = {
+  id: "require-limit",
+  severity: "warning",
+  check(metadata) {
+    const results = [];
+    for (const relation of metadata.relations) {
+      if (relation.type !== "hasMany") continue;
+      const limit = relation.options?.limit;
+      if (!limit || limit.default === void 0 || limit.max === void 0) {
+        const kb = Object.keys(relation.keyBinding).join(", ");
+        results.push({
+          ruleId: "require-limit",
+          severity: "warning",
+          message: `hasMany relation (keyBinding: [${kb}]) on entity '${metadata.prefix}' is missing limit.default or limit.max. Unbounded queries may consume excessive RCU.`,
+          entity: metadata.prefix
+        });
+      }
+    }
+    return results;
+  }
+};
+
+// src/linter/rules/gsi-ambiguity.ts
+function isSubsetOf(a, b) {
+  const setB = new Set(b);
+  return a.length > 0 && a.every((f) => setB.has(f));
+}
+var gsiAmbiguityRule = {
+  id: "gsi-ambiguity",
+  severity: "error",
+  check(metadata) {
+    const results = [];
+    const patterns = [];
+    if (metadata.primaryKey) {
+      patterns.push({
+        label: "primaryKey",
+        fieldNames: metadata.primaryKey.inputFieldNames
+      });
+    }
+    for (const gsi2 of metadata.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;
+          results.push({
+            ruleId: "gsi-ambiguity",
+            severity: "error",
+            message: `Ambiguous GSI resolution: field set [${smaller.fieldNames.join(", ")}] matches both '${a.label}' and '${b.label}'. Each access pattern must have a unique field combination.`,
+            entity: metadata.prefix,
+            field: smaller.fieldNames.join(", ")
+          });
+        }
+      }
+    }
+    return results;
+  }
+};
+
+// src/planner/key-resolver.ts
+function fieldSetsEqual(a, b) {
+  if (a.length !== b.length) return false;
+  const sorted = [...b].sort();
+  return [...a].sort().every((v, i) => v === sorted[i]);
+}
+function classifySegmentMatch(segmented, queryFields) {
+  const pkFields = segmentFieldNames(segmented.pkSegments);
+  const present = new Set(queryFields);
+  const allFields = /* @__PURE__ */ new Set([
+    ...pkFields,
+    ...segmentFieldNames(segmented.skSegments)
+  ]);
+  for (const f of queryFields) {
+    if (!allFields.has(f)) return null;
+  }
+  for (const f of pkFields) {
+    if (!present.has(f)) return null;
+  }
+  const sk = segmented.skSegments;
+  let consumed = 0;
+  let truncated = false;
+  for (let i = 0; i < sk.length; i++) {
+    const fields = sk[i].columns.map((c) => c.name);
+    const all = fields.every((f) => present.has(f));
+    const any = fields.some((f) => present.has(f));
+    if (all && fields.length > 0) {
+      if (truncated) return null;
+      consumed = i + 1;
+      continue;
+    }
+    if (fields.length === 0) {
+      if (!truncated) consumed = i + 1;
+      continue;
+    }
+    if (any) return null;
+    truncated = true;
+  }
+  const skFieldCount = segmentFieldNames(sk).length;
+  const allSkPresent = segmentFieldNames(sk).every((f) => present.has(f));
+  if (skFieldCount === 0 || allSkPresent && consumed === sk.length) {
+    return "full";
+  }
+  return "partial";
+}
+function resolveKey(queryFields, metadata) {
+  if (metadata.primaryKey && fieldSetsEqual(queryFields, metadata.primaryKey.inputFieldNames)) {
+    return {
+      type: "pk",
+      partial: false,
+      inputFieldNames: metadata.primaryKey.inputFieldNames
+    };
+  }
+  for (const gsi2 of metadata.gsiDefinitions) {
+    if (fieldSetsEqual(queryFields, gsi2.inputFieldNames)) {
+      return {
+        type: "gsi",
+        indexName: gsi2.indexName,
+        unique: gsi2.unique,
+        partial: false,
+        inputFieldNames: gsi2.inputFieldNames
+      };
+    }
+  }
+  if (metadata.primaryKey) {
+    const match = classifySegmentMatch(metadata.primaryKey.segmented, queryFields);
+    if (match === "partial") {
+      return { type: "pk", partial: true, inputFieldNames: queryFields };
+    }
+    if (match === "full") {
+      return { type: "pk", partial: false, inputFieldNames: queryFields };
+    }
+  }
+  for (const gsi2 of metadata.gsiDefinitions) {
+    const match = classifySegmentMatch(gsi2.segmented, queryFields);
+    if (match === "partial") {
+      return {
+        type: "gsi",
+        indexName: gsi2.indexName,
+        unique: false,
+        partial: true,
+        inputFieldNames: queryFields
+      };
+    }
+    if (match === "full") {
+      return {
+        type: "gsi",
+        indexName: gsi2.indexName,
+        unique: gsi2.unique,
+        partial: false,
+        inputFieldNames: queryFields
+      };
+    }
+  }
+  throw new Error(
+    `No access pattern found for fields [${queryFields.join(", ")}]. Available: primaryKey([${metadata.primaryKey?.inputFieldNames.join(", ") ?? ""}])` + metadata.gsiDefinitions.map((g) => `, ${g.indexName}([${g.inputFieldNames.join(", ")}])`).join("")
+  );
+}
+
+// src/linter/rules/missing-gsi.ts
+var missingGsiRule = {
+  id: "missing-gsi",
+  severity: "error",
+  check(metadata, registry) {
+    const results = [];
+    for (const relation of metadata.relations) {
+      const targetFields = Object.keys(relation.keyBinding);
+      if (targetFields.length === 0) {
+        continue;
+      }
+      let targetMeta;
+      try {
+        const targetClass = relation.targetFactory();
+        targetMeta = registry.get(targetClass);
+      } catch {
+        results.push({
+          ruleId: "missing-gsi",
+          severity: "error",
+          message: `Relation '${relation.propertyName}' on entity '${metadata.prefix}' targets an entity that is not registered in MetadataRegistry.`,
+          entity: metadata.prefix,
+          field: relation.propertyName
+        });
+        continue;
+      }
+      try {
+        resolveKey(targetFields, targetMeta);
+      } catch {
+        results.push({
+          ruleId: "missing-gsi",
+          severity: "error",
+          message: `Relation '${relation.propertyName}' on entity '${metadata.prefix}' requires access pattern [${targetFields.join(", ")}] on target entity '${targetMeta.prefix}', but no matching primary key or GSI is defined.`,
+          entity: metadata.prefix,
+          field: relation.propertyName
+        });
+      }
+    }
+    return results;
+  }
+};
+
+// src/linter/rules/relation-depth.ts
+var DEFAULT_MAX_DEPTH = 1;
+function computeRelationDepth(metadata, registry, visited = /* @__PURE__ */ new Set()) {
+  if (metadata.relations.length === 0) {
+    return 0;
+  }
+  let maxDepth = 0;
+  for (const relation of metadata.relations) {
+    let targetClass;
+    try {
+      targetClass = relation.targetFactory();
+    } catch {
+      continue;
+    }
+    if (visited.has(targetClass)) {
+      continue;
+    }
+    let targetMeta;
+    try {
+      targetMeta = registry.get(targetClass);
+    } catch {
+      continue;
+    }
+    const nextVisited = new Set(visited);
+    nextVisited.add(targetClass);
+    const childDepth = 1 + computeRelationDepth(targetMeta, registry, nextVisited);
+    maxDepth = Math.max(maxDepth, childDepth);
+  }
+  return maxDepth;
+}
+var relationDepthRule = {
+  id: "relation-depth",
+  severity: "warning",
+  check(metadata, registry) {
+    const depth = computeRelationDepth(metadata, registry);
+    if (depth <= DEFAULT_MAX_DEPTH) {
+      return [];
+    }
+    return [
+      {
+        ruleId: "relation-depth",
+        severity: "warning",
+        message: `Entity '${metadata.prefix}' has relation paths exceeding default maxDepth ${DEFAULT_MAX_DEPTH} (detected depth: ${depth}). Deep traversal requires explicit maxDepth at runtime.`,
+        entity: metadata.prefix
+      }
+    ];
+  }
+};
+
+// src/linter/default-linter.ts
+function createDefaultLinter() {
+  const linter = new Linter();
+  linter.addRule(noScanRule);
+  linter.addRule(requireLimitRule);
+  linter.addRule(gsiAmbiguityRule);
+  linter.addRule(missingGsiRule);
+  linter.addRule(relationDepthRule);
+  return linter;
+}
+
+// src/metadata/registry.ts
+var MetadataRegistry = class {
+  static store = /* @__PURE__ */ new Map();
+  static _linter = createDefaultLinter();
+  static register(target, metadata) {
+    this.store.set(target, { ...metadata, _finalized: false });
+  }
+  static get(target) {
+    const meta = this.store.get(target);
+    if (!meta) {
+      throw new Error(
+        `No metadata registered for '${target.name ?? "(anonymous)"}'. Did you apply @model() to this class?`
+      );
+    }
+    if (!meta._finalized) {
+      this.finalize(target, meta);
+    }
+    return meta;
+  }
+  static has(target) {
+    return this.store.has(target);
+  }
+  static getAll() {
+    for (const [target, meta] of this.store) {
+      if (!meta._finalized) {
+        this.finalize(target, meta);
+      }
+    }
+    return new Map(this.store);
+  }
+  static get linter() {
+    return this._linter;
+  }
+  static set linter(linter) {
+    this._linter = linter;
+  }
+  /** Resets linter to the default built-in rule set. */
+  static resetLinter() {
+    this._linter = createDefaultLinter();
+  }
+  /** @internal — for testing only */
+  static clear() {
+    this.store.clear();
+    this._linter = new Linter();
+  }
+  static finalize(target, meta) {
+    for (const name of Object.getOwnPropertyNames(target)) {
+      let value;
+      try {
+        value = target[name];
+      } catch {
+        continue;
+      }
+      if (isKeyDefinition(value)) {
+        meta.primaryKey = {
+          segmented: value.segmented,
+          inputFieldNames: value.inputFieldNames
+        };
+      } else if (isGsiDefinition(value)) {
+        meta.gsiDefinitions.push({
+          indexName: value.indexName,
+          segmented: value.segmented,
+          inputFieldNames: value.inputFieldNames,
+          unique: value.unique
+        });
+      }
+    }
+    const results = this._linter.run(meta, this);
+    this.handleLintResults(results);
+    meta._finalized = true;
+  }
+  static handleLintResults(results) {
+    const errors = [];
+    for (const result of results) {
+      if (result.severity === "error") {
+        errors.push(result);
+      } else if (result.severity === "warning") {
+        console.warn(`[graphddb] ${result.ruleId}: ${result.message}`);
+      }
+    }
+    if (errors.length > 0) {
+      const messages = errors.map((e) => `${e.ruleId}: ${e.message}`).join("\n");
+      throw new Error(`Entity lint errors:
+${messages}`);
+    }
+  }
+};
+
+// src/client/TableMapping.ts
+var TableMapping = class {
+  static mapping = {};
+  static set(mapping) {
+    this.mapping = { ...mapping };
+  }
+  static resolve(declaredName) {
+    return this.mapping[declaredName] ?? declaredName;
+  }
+  /** @internal — for testing only */
+  static reset() {
+    this.mapping = {};
+  }
+};
+
+// src/client/lib-dynamodb.ts
+var cached = null;
+async function loadLibDynamoDB() {
+  return cached ??= await import("@aws-sdk/lib-dynamodb");
+}
+
+// src/operations/batch-retry.ts
+var BATCH_GET_MAX_KEYS = 100;
+var BATCH_WRITE_MAX_ITEMS = 25;
+var BATCH_MAX_RETRY_ATTEMPTS = 10;
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function computeBackoffDelay(attempt) {
+  return Math.min(1e3, 50 * 2 ** (attempt - 1));
+}
+function chunkArray(items, size) {
+  const chunks = [];
+  for (let i = 0; i < items.length; i += size) {
+    chunks.push(items.slice(i, i + size));
+  }
+  return chunks;
+}
+async function batchGetChunkWithRetry(docClient, tableName, request) {
+  const { BatchGetCommand } = await loadLibDynamoDB();
+  let pendingKeys = request.Keys;
+  let attempt = 0;
+  const items = [];
+  while (pendingKeys.length > 0) {
+    const cmd = new BatchGetCommand({
+      RequestItems: {
+        [tableName]: {
+          ...request,
+          Keys: pendingKeys
+        }
+      }
+    });
+    const result = await docClient.send(cmd);
+    const response = result.Responses?.[tableName] ?? [];
+    items.push(...response);
+    const unprocessed = result.UnprocessedKeys?.[tableName]?.Keys ?? [];
+    if (unprocessed.length === 0) {
+      break;
+    }
+    if (attempt >= BATCH_MAX_RETRY_ATTEMPTS) {
+      throw new Error(
+        `BatchGet exceeded the maximum of ${BATCH_MAX_RETRY_ATTEMPTS} retry attempts with ${unprocessed.length} key(s) still unprocessed for table "${tableName}". DynamoDB kept returning UnprocessedKeys (likely sustained throttling).`
+      );
+    }
+    pendingKeys = unprocessed;
+    attempt += 1;
+    await sleep(computeBackoffDelay(attempt));
+  }
+  return items;
+}
+async function batchWriteChunkWithRetry(docClient, tableName, entries, toCommandItem, matchUnprocessed2) {
+  const { BatchWriteCommand } = await loadLibDynamoDB();
+  let pendingEntries = entries;
+  let attempt = 0;
+  while (pendingEntries.length > 0) {
+    const cmd = new BatchWriteCommand({
+      RequestItems: {
+        [tableName]: pendingEntries.map(toCommandItem)
+      }
+    });
+    const result = await docClient.send(cmd);
+    const unprocessed = result.UnprocessedItems?.[tableName] ?? [];
+    if (unprocessed.length === 0) {
+      return;
+    }
+    if (attempt >= BATCH_MAX_RETRY_ATTEMPTS) {
+      throw new Error(
+        `BatchWrite exceeded the maximum of ${BATCH_MAX_RETRY_ATTEMPTS} retry attempts with ${unprocessed.length} item(s) still unprocessed for table "${tableName}". DynamoDB kept returning UnprocessedItems (likely sustained throttling).`
+      );
+    }
+    pendingEntries = matchUnprocessed2(unprocessed, pendingEntries);
+    attempt += 1;
+    await sleep(computeBackoffDelay(attempt));
+  }
+}
+
+// src/client/ClientManager.ts
+var ClientManager = class {
+  static client = null;
+  static documentClient = null;
+  /**
+   * The active I/O executor (issue #76). `null` ⇒ use the lazily-constructed
+   * default {@link DynamoExecutor}. Tests / the memory adapter replace it via
+   * {@link setExecutor}. Constructed lazily (and imported lazily) so importing
+   * GraphDDB for planning / linting / codegen never pulls in the AWS SDK.
+   */
+  static executor = null;
+  static defaultExecutor = null;
+  static setClient(client) {
+    this.client = client;
+    this.documentClient = null;
+  }
+  static getClient() {
+    if (!this.client) {
+      throw new Error(
+        "DynamoDB client is not configured. Call DDBModel.setClient(new DynamoDBClient({...})) first."
+      );
+    }
+    return this.client;
+  }
+  static async getDocumentClient() {
+    if (!this.documentClient) {
+      const client = this.getClient();
+      const { DynamoDBDocumentClient: DocClient } = await import("@aws-sdk/lib-dynamodb");
+      this.documentClient = DocClient.from(client);
+    }
+    return this.documentClient;
+  }
+  /**
+   * The active I/O executor (issue #76). All read/write I/O flows through this
+   * seam. Defaults to a {@link DynamoExecutor} (current real-DynamoDB
+   * behavior); tests inject a `MemoryExecutor` via {@link setExecutor}.
+   *
+   * The default is constructed lazily and imported lazily so importing
+   * GraphDDB for planning / linting / codegen does not eagerly load the
+   * executor module graph.
+   */
+  static getExecutor() {
+    if (this.executor) {
+      return this.executor;
+    }
+    if (!this.defaultExecutor) {
+      this.defaultExecutor = new DynamoExecutor();
+    }
+    return this.defaultExecutor;
+  }
+  /** Inject a custom executor (test adapter / memory engine). */
+  static setExecutor(executor) {
+    this.executor = executor;
+  }
+  /** Restore the default {@link DynamoExecutor}. */
+  static resetExecutor() {
+    this.executor = null;
+  }
+  /** @internal — for testing only */
+  static reset() {
+    this.client = null;
+    this.documentClient = null;
+    this.executor = null;
+  }
+};
+
+// src/executor/batch-executor.ts
+async function executeBatchGet(docClient, operation) {
+  if (operation.keys.length === 0) {
+    return { items: [] };
+  }
+  const chunks = chunkArray(operation.keys, BATCH_GET_MAX_KEYS);
+  const chunkResults = await Promise.all(
+    chunks.map(
+      (chunk) => batchGetChunkWithRetry(docClient, operation.tableName, {
+        Keys: chunk,
+        ...operation.projectionExpression ? { ProjectionExpression: operation.projectionExpression } : {},
+        ...operation.expressionAttributeNames ? { ExpressionAttributeNames: operation.expressionAttributeNames } : {},
+        ...operation.consistentRead ? { ConsistentRead: true } : {}
+      })
+    )
+  );
+  const allItems = [];
+  for (const chunkItems of chunkResults) {
+    allItems.push(...chunkItems);
+  }
+  return { items: allItems };
+}
+
+// src/executor/dynamo-executor.ts
+var DynamoExecutor = class {
+  async execute(operation) {
+    const docClient = await ClientManager.getDocumentClient();
+    if (operation.type === "GetItem") {
+      return executeGetItem(docClient, operation);
+    }
+    if (operation.type === "BatchGetItem") {
+      return this.batchGet(operation);
+    }
+    return executeQuery(docClient, operation);
+  }
+  async batchGet(input) {
+    const docClient = await ClientManager.getDocumentClient();
+    return executeBatchGet(docClient, { type: "BatchGetItem", ...input });
+  }
+  async put(input, options) {
+    const docClient = await ClientManager.getDocumentClient();
+    const { PutCommand } = await loadLibDynamoDB();
+    const result = await docClient.send(
+      new PutCommand(
+        options?.returnOldImage ? { ...input, ReturnValues: "ALL_OLD" } : input
+      )
+    );
+    return toWriteResult(result);
+  }
+  async update(input, options) {
+    const docClient = await ClientManager.getDocumentClient();
+    const { UpdateCommand } = await loadLibDynamoDB();
+    const result = await docClient.send(
+      new UpdateCommand(
+        options?.returnOldImage ? { ...input, ReturnValues: "ALL_OLD" } : input
+      )
+    );
+    return toWriteResult(result);
+  }
+  async delete(input, options) {
+    const docClient = await ClientManager.getDocumentClient();
+    const { DeleteCommand } = await loadLibDynamoDB();
+    const result = await docClient.send(
+      new DeleteCommand(
+        options?.returnOldImage ? { ...input, ReturnValues: "ALL_OLD" } : input
+      )
+    );
+    return toWriteResult(result);
+  }
+  async batchWrite(tableName, items) {
+    const docClient = await ClientManager.getDocumentClient();
+    for (const chunk of chunkArray(items, BATCH_WRITE_MAX_ITEMS)) {
+      await batchWriteChunkWithRetry(
+        docClient,
+        tableName,
+        chunk,
+        toBatchWriteCommandItem,
+        matchUnprocessed
+      );
+    }
+  }
+  async transactWrite(items) {
+    if (items.length === 0) return;
+    const docClient = await ClientManager.getDocumentClient();
+    const { TransactWriteCommand } = await loadLibDynamoDB();
+    await docClient.send(
+      new TransactWriteCommand({ TransactItems: items })
+    );
+  }
+};
+function toWriteResult(result) {
+  const oldItem = result.Attributes;
+  return oldItem ? { oldItem } : {};
+}
+function toBatchWriteCommandItem(item) {
+  if (item.type === "put") {
+    return { PutRequest: { Item: item.item } };
+  }
+  return { DeleteRequest: { Key: item.key } };
+}
+function matchUnprocessed(unprocessed, items) {
+  return unprocessed.map((u) => {
+    if (u.PutRequest?.Item) {
+      const { PK, SK } = u.PutRequest.Item;
+      const match = items.find(
+        (it) => it.type === "put" && it.item.PK === PK && it.item.SK === SK
+      );
+      if (!match) {
+        throw new Error("Unable to match unprocessed BatchWrite put request");
+      }
+      return match;
+    }
+    if (u.DeleteRequest?.Key) {
+      const { PK, SK } = u.DeleteRequest.Key;
+      const match = items.find(
+        (it) => it.type === "delete" && it.key.PK === PK && it.key.SK === SK
+      );
+      if (!match) {
+        throw new Error("Unable to match unprocessed BatchWrite delete request");
+      }
+      return match;
+    }
+    throw new Error("Unsupported unprocessed BatchWrite request shape");
+  });
+}
+async function executeGetItem(docClient, operation) {
+  const { GetCommand } = await loadLibDynamoDB();
+  const cmd = new GetCommand({
+    TableName: operation.tableName,
+    Key: operation.keyCondition,
+    ...operation.projectionExpression ? { ProjectionExpression: operation.projectionExpression } : {},
+    ...operation.expressionAttributeNames ? { ExpressionAttributeNames: operation.expressionAttributeNames } : {},
+    ...operation.consistentRead ? { ConsistentRead: true } : {}
+  });
+  const result = await docClient.send(cmd);
+  if (result.Item) {
+    return { items: [result.Item] };
+  }
+  return { items: [] };
+}
+async function executeQuery(docClient, operation) {
+  const { QueryCommand } = await loadLibDynamoDB();
+  const keyEntries = Object.entries(operation.keyCondition);
+  const conditionParts = [];
+  const exprAttrNames = {
+    ...operation.expressionAttributeNames ?? {},
+    ...operation.filterExpressionAttributeNames ?? {}
+  };
+  const exprAttrValues = {
+    ...operation.filterExpressionAttributeValues ?? {}
+  };
+  for (let i = 0; i < keyEntries.length; i++) {
+    const [attrName, value] = keyEntries[i];
+    const nameAlias = `#k${i}`;
+    const valueAlias = `:k${i}`;
+    exprAttrNames[nameAlias] = attrName;
+    exprAttrValues[valueAlias] = value;
+    conditionParts.push(`${nameAlias} = ${valueAlias}`);
+  }
+  if (operation.rangeCondition) {
+    const rc = operation.rangeCondition;
+    const idx = keyEntries.length;
+    const nameAlias = `#k${idx}`;
+    const valueAlias = `:k${idx}`;
+    exprAttrNames[nameAlias] = rc.key;
+    exprAttrValues[valueAlias] = rc.value;
+    conditionParts.push(`begins_with(${nameAlias}, ${valueAlias})`);
+  }
+  const cmd = new QueryCommand({
+    TableName: operation.tableName,
+    KeyConditionExpression: conditionParts.join(" AND "),
+    ExpressionAttributeNames: exprAttrNames,
+    ExpressionAttributeValues: exprAttrValues,
+    ...operation.indexName ? { IndexName: operation.indexName } : {},
+    ...operation.filterExpression ? { FilterExpression: operation.filterExpression } : {},
+    ...operation.projectionExpression ? { ProjectionExpression: operation.projectionExpression } : {},
+    ...operation.scanIndexForward != null ? { ScanIndexForward: operation.scanIndexForward } : {},
+    ...operation.limit != null ? { Limit: operation.limit } : {},
+    ...operation.exclusiveStartKey ? { ExclusiveStartKey: operation.exclusiveStartKey } : {},
+    ...operation.consistentRead ? { ConsistentRead: true } : {}
+  });
+  const result = await docClient.send(cmd);
+  return {
+    items: result.Items ?? [],
+    lastEvaluatedKey: result.LastEvaluatedKey
+  };
+}
+
+// src/expression/condition-expression.ts
+function buildConditionExpression(condition) {
+  if (condition.notExists === true) {
+    return {
+      expression: "attribute_not_exists(PK)",
+      names: {},
+      values: {}
+    };
+  }
+  if (typeof condition.attributeExists === "string") {
+    const field = condition.attributeExists;
+    const nameKey = `#cond_${field}`;
+    return {
+      expression: `attribute_exists(${nameKey})`,
+      names: { [nameKey]: field },
+      values: {}
+    };
+  }
+  if (typeof condition.attributeNotExists === "string") {
+    const field = condition.attributeNotExists;
+    const nameKey = `#cond_${field}`;
+    return {
+      expression: `attribute_not_exists(${nameKey})`,
+      names: { [nameKey]: field },
+      values: {}
+    };
+  }
+  const clauses = [];
+  const names = {};
+  const values = {};
+  let counter = 0;
+  for (const [fieldName, value] of Object.entries(condition)) {
+    const nameKey = `#cond_${fieldName}`;
+    const valueKey = `:cond${counter++}`;
+    names[nameKey] = fieldName;
+    values[valueKey] = value;
+    clauses.push(`${nameKey} = ${valueKey}`);
+  }
+  return {
+    expression: clauses.join(" AND "),
+    names,
+    values
+  };
+}
+
+// src/operations/serialize.ts
+function serializeFieldValue(value, fieldMeta) {
+  if (fieldMeta.options?.serialize) {
+    return fieldMeta.options.serialize(value);
+  }
+  if (value instanceof Date) {
+    if (fieldMeta.options?.format === "date") {
+      return value.toISOString().split("T")[0];
+    }
+    if (fieldMeta.options?.format === "datetime") {
+      return value.toISOString();
+    }
+  }
+  return value;
+}
+
+// src/metadata/segments.ts
+var SEGMENT_DELIMITER = "#";
+function segmentComplete(segment, values) {
+  return segment.columns.every((col) => {
+    const v = values[col.name];
+    return v !== void 0 && v !== null;
+  });
+}
+function renderSegment(segment, values) {
+  let out = segment.literals[0];
+  for (let i = 0; i < segment.columns.length; i++) {
+    out += String(values[segment.columns[i].name]);
+    out += segment.literals[i + 1];
+  }
+  return out;
+}
+function segmentTemplate(segment, scope = "param", nameOf = (f) => f) {
+  let out = segment.literals[0];
+  for (let i = 0; i < segment.columns.length; i++) {
+    const name = nameOf(segment.columns[i].name);
+    out += scope === "result" ? `{result.${name}}` : `{${name}}`;
+    out += segment.literals[i + 1];
+  }
+  return out;
+}
+function pkTemplate(segmented, scope = "param", nameOf = (f) => f) {
+  return segmented.pkSegments.map((s) => segmentTemplate(s, scope, nameOf)).join(SEGMENT_DELIMITER);
+}
+function walkSkSegments(segments, isPresent, context) {
+  if (segments.length === 0) return null;
+  let consumed = 0;
+  let truncatedAt = -1;
+  let boundaryLiteral = "";
+  for (let i = 0; i < segments.length; i++) {
+    const seg = segments[i];
+    const fields = seg.columns.map((c) => c.name);
+    const all = fields.every((f) => isPresent(f));
+    const any = fields.some((f) => isPresent(f));
+    if (fields.length === 0) {
+      if (truncatedAt < 0) consumed = i + 1;
+      continue;
+    }
+    if (all) {
+      if (truncatedAt >= 0) {
+        throw new Error(
+          `Non-contiguous ${context}: segment #${i} is supplied but the earlier segment #${truncatedAt} is missing. Segments must be a contiguous prefix.`
+        );
+      }
+      consumed = i + 1;
+      continue;
+    }
+    if (any) {
+      throw new Error(
+        `Non-contiguous ${context}: segment #${i} has some but not all of its fields supplied. Segments must be a contiguous prefix.`
+      );
+    }
+    if (truncatedAt < 0) {
+      truncatedAt = i;
+      boundaryLiteral = seg.literals[0] ?? "";
+    }
+  }
+  const truncated = truncatedAt >= 0;
+  if (!truncated) {
+    return { consumed, truncated: false, boundaryLiteral: "" };
+  }
+  if (consumed === 0 && boundaryLiteral === "") return null;
+  return { consumed, truncated: true, boundaryLiteral };
+}
+function skTemplate(segmented, presentFields, scope = "param", nameOf = (f) => f, context = "sort key") {
+  const segments = segmented.skSegments;
+  const isPresent = (f) => presentFields === void 0 || presentFields.has(f);
+  const walk = walkSkSegments(segments, isPresent, context);
+  if (!walk) return void 0;
+  const consumedPart = segments.slice(0, walk.consumed).map((s) => segmentTemplate(s, scope, nameOf)).join(SEGMENT_DELIMITER);
+  if (!walk.truncated) {
+    return { template: consumedPart, truncated: false };
+  }
+  return {
+    template: composeTruncated(consumedPart, walk.boundaryLiteral),
+    truncated: true
+  };
+}
+function composeTruncated(consumedPart, boundaryLiteral) {
+  let out = consumedPart;
+  if (out !== "") out += SEGMENT_DELIMITER;
+  out += boundaryLiteral;
+  if (!out.endsWith(SEGMENT_DELIMITER)) out += SEGMENT_DELIMITER;
+  return out;
+}
+function resolveSegmentedKey(segmented, values, context = "key") {
+  for (const seg of segmented.pkSegments) {
+    if (!segmentComplete(seg, values)) {
+      const missing = seg.columns.filter((c) => values[c.name] === void 0 || values[c.name] === null).map((c) => `'${c.name}'`).join(", ");
+      throw new Error(
+        `Cannot resolve ${context}: partition-key field(s) ${missing} are missing. Every partition-key segment must be supplied.`
+      );
+    }
+  }
+  const pk = segmented.pkSegments.map((s) => renderSegment(s, values)).join(SEGMENT_DELIMITER);
+  const isPresent = (f) => {
+    const v = values[f];
+    return v !== void 0 && v !== null;
+  };
+  const walk = walkSkSegments(segmented.skSegments, isPresent, `${context} (sort key)`);
+  if (!walk) return { pk, sk: void 0, skTruncated: false };
+  const consumedPart = segmented.skSegments.slice(0, walk.consumed).map((s) => renderSegment(s, values)).join(SEGMENT_DELIMITER);
+  if (!walk.truncated) {
+    return { pk, sk: consumedPart, skTruncated: false };
+  }
+  return {
+    pk,
+    sk: composeTruncated(consumedPart, walk.boundaryLiteral),
+    skTruncated: true
+  };
+}
+
+// src/capture/registry.ts
+var ChangeCaptureRegistryImpl = class {
+  subscribers = /* @__PURE__ */ new Set();
+  /**
+   * Stream-enable opt-in, keyed by the model class. A model is only eligible to
+   * have its pre-write image fetched (`ReturnValues: ALL_OLD`) when it has been
+   * explicitly stream-enabled here. Default is disabled.
+   */
+  streamEnabled = /* @__PURE__ */ new Set();
+  /** Register an internal subscriber. Returns an idempotent unsubscribe. */
+  register(subscriber) {
+    this.subscribers.add(subscriber);
+    let active = true;
+    return () => {
+      if (!active) return;
+      active = false;
+      this.subscribers.delete(subscriber);
+    };
+  }
+  /** True when at least one subscriber is live. Cheap fast-path gate. */
+  hasSubscribers() {
+    return this.subscribers.size > 0;
+  }
+  /** Mark a model class stream-enabled (opt-in). */
+  enableStream(modelClass) {
+    this.streamEnabled.add(modelClass);
+  }
+  /** Disable streaming for a model class. */
+  disableStream(modelClass) {
+    this.streamEnabled.delete(modelClass);
+  }
+  /** True when the model class has been stream-enabled. */
+  isStreamEnabled(modelClass) {
+    return this.streamEnabled.has(modelClass);
+  }
+  /**
+   * Whether the originating write should request a pre-write image
+   * (`ReturnValues: ALL_OLD`). Per spec §5 this is added **only when** the model
+   * is stream-enabled AND a subscriber is live, so the OldImage cost is never
+   * paid when nobody is listening.
+   */
+  wantsOldImage(modelClass) {
+    return this.hasSubscribers() && this.streamEnabled.has(modelClass);
+  }
+  /**
+   * Deliver one raw write to every subscriber. Each subscriber is isolated:
+   * a throw is swallowed so it neither fails the originating write nor blocks
+   * other subscribers (spec §14 default).
+   */
+  emit(record) {
+    if (this.subscribers.size === 0) return;
+    for (const subscriber of [...this.subscribers]) {
+      try {
+        subscriber(record);
+      } catch {
+      }
+    }
+  }
+  /** @internal — test-only full reset. */
+  reset() {
+    this.subscribers.clear();
+    this.streamEnabled.clear();
+  }
+};
+var ChangeCaptureRegistry = new ChangeCaptureRegistryImpl();
+function captureWrite(record) {
+  ChangeCaptureRegistry.emit(record);
+}
+
+// src/operations/put.ts
+function buildPutInput(modelClass, item, options) {
+  const meta = MetadataRegistry.get(modelClass);
+  if (!meta.primaryKey) {
+    throw new Error(
+      `No primary key defined for '${modelClass.name}'. Ensure the model has a static \`keys = key(...)\` definition.`
+    );
+  }
+  const tableName = TableMapping.resolve(meta.tableName);
+  const serialized = {};
+  for (const fieldMeta of meta.fields) {
+    const value = item[fieldMeta.propertyName];
+    if (value !== void 0) {
+      serialized[fieldMeta.propertyName] = serializeFieldValue(value, fieldMeta);
+    }
+  }
+  const keyInput = {};
+  for (const fieldName of meta.primaryKey.inputFieldNames) {
+    keyInput[fieldName] = serialized[fieldName] ?? item[fieldName];
+  }
+  const { pk, sk } = resolveSegmentedKey(
+    meta.primaryKey.segmented,
+    keyInput,
+    `${modelClass.name} primary key`
+  );
+  const dynamoItem = {
+    PK: pk,
+    SK: sk ?? "",
+    ...serialized
+  };
+  for (const emb of meta.embeddedFields) {
+    const value = item[emb.propertyName];
+    if (value !== void 0) {
+      dynamoItem[emb.propertyName] = value;
+    }
+  }
+  for (const gsi2 of meta.gsiDefinitions) {
+    const gsiInput = {};
+    for (const fieldName of gsi2.inputFieldNames) {
+      gsiInput[fieldName] = serialized[fieldName] ?? item[fieldName];
+    }
+    const { pk: gsiPk, sk: gsiSk } = resolveSegmentedKey(
+      gsi2.segmented,
+      gsiInput,
+      `${modelClass.name} GSI '${gsi2.indexName}'`
+    );
+    dynamoItem[`${gsi2.indexName}PK`] = gsiPk;
+    dynamoItem[`${gsi2.indexName}SK`] = gsiSk ?? "";
+  }
+  const putInput = {
+    TableName: tableName,
+    Item: dynamoItem
+  };
+  if (options?.condition) {
+    const condResult = buildConditionExpression(options.condition);
+    putInput.ConditionExpression = condResult.expression;
+    if (Object.keys(condResult.names).length > 0) {
+      putInput.ExpressionAttributeNames = condResult.names;
+    }
+    if (Object.keys(condResult.values).length > 0) {
+      putInput.ExpressionAttributeValues = condResult.values;
+    }
+  }
+  return putInput;
+}
+async function executePut(modelClass, item, options) {
+  const putInput = buildPutInput(modelClass, item, options);
+  const wantsOld = ChangeCaptureRegistry.wantsOldImage(modelClass);
+  const result = await ClientManager.getExecutor().put(
+    putInput,
+    wantsOld ? { returnOldImage: true } : void 0
+  );
+  if (ChangeCaptureRegistry.hasSubscribers()) {
+    const oldItem = result.oldItem;
+    captureWrite({
+      table: putInput.TableName,
+      model: modelClass.name,
+      op: "put",
+      keys: { pk: String(putInput.Item.PK), sk: String(putInput.Item.SK ?? "") },
+      newItem: putInput.Item,
+      ...oldItem ? { oldItem } : {}
+    });
+  }
+}
+
+// src/expression/update-expression.ts
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) && !(value instanceof Date);
+}
+function flattenChanges(obj, parentPath, embeddedFieldNames) {
+  const sets = [];
+  const removes = [];
+  for (const [fieldName, value] of Object.entries(obj)) {
+    const currentPath = [...parentPath, fieldName];
+    if (value === void 0) {
+      removes.push({ path: currentPath });
+    } else if (embeddedFieldNames.has(currentPath[0]) && isPlainObject(value)) {
+      const nested = flattenChanges(value, currentPath, embeddedFieldNames);
+      sets.push(...nested.sets);
+      removes.push(...nested.removes);
+    } else {
+      sets.push({ path: currentPath, value });
+    }
+  }
+  return { sets, removes };
+}
+function buildUpdateExpression(changes, embeddedFieldNames) {
+  const { sets, removes } = flattenChanges(changes, [], embeddedFieldNames);
+  if (sets.length === 0 && removes.length === 0) {
+    throw new Error("No changes provided for update.");
+  }
+  const names = {};
+  const values = {};
+  let valueCounter = 0;
+  const setClauses = [];
+  for (const op of sets) {
+    const pathExpr = op.path.map((segment) => {
+      const nameKey = `#${segment}`;
+      names[nameKey] = segment;
+      return nameKey;
+    }).join(".");
+    const valueKey = `:val${valueCounter++}`;
+    values[valueKey] = op.value;
+    setClauses.push(`${pathExpr} = ${valueKey}`);
+  }
+  const removeClauses = [];
+  for (const op of removes) {
+    const pathExpr = op.path.map((segment) => {
+      const nameKey = `#${segment}`;
+      names[nameKey] = segment;
+      return nameKey;
+    }).join(".");
+    removeClauses.push(pathExpr);
+  }
+  const parts = [];
+  if (setClauses.length > 0) {
+    parts.push(`SET ${setClauses.join(", ")}`);
+  }
+  if (removeClauses.length > 0) {
+    parts.push(`REMOVE ${removeClauses.join(", ")}`);
+  }
+  return {
+    expression: parts.join(" "),
+    names,
+    values
+  };
+}
+
+// src/hydrator/hidden-key.ts
+var GRAPHDDB_KEY = /* @__PURE__ */ Symbol("graphddb:key");
+function attachHiddenKey(result, raw) {
+  const pk = raw.PK;
+  if (typeof pk !== "string") {
+    throw new Error(
+      "Cannot attach updatable key: raw item is missing a string `PK` attribute."
+    );
+  }
+  const sk = raw.SK;
+  const value = {
+    PK: pk,
+    SK: typeof sk === "string" ? sk : ""
+  };
+  Object.defineProperty(result, GRAPHDDB_KEY, {
+    value,
+    enumerable: false,
+    writable: false,
+    configurable: false
+  });
+  return result;
+}
+function readHiddenKey(entity) {
+  const value = entity[GRAPHDDB_KEY];
+  if (value === void 0) return void 0;
+  return value;
+}
+
+// src/operations/update.ts
+function resolveUpdateKey(modelClass, primaryKey, entity, fieldMap) {
+  const hidden = readHiddenKey(entity);
+  if (hidden) {
+    return { pk: hidden.PK, sk: hidden.SK };
+  }
+  const missing = primaryKey.inputFieldNames.filter(
+    (f) => entity[f] === void 0
+  );
+  if (missing.length > 0) {
+    const fieldList = missing.join(", ");
+    throw new Error(
+      `Cannot resolve update key for '${modelClass.name}': missing key field(s) [${fieldList}]. Provide an explicit key (update({ ${fieldList} }, changes)), select all key fields, or query with { updatable: true }.`
+    );
+  }
+  const keyInput = {};
+  for (const fieldName of primaryKey.inputFieldNames) {
+    let value = entity[fieldName];
+    const fieldMeta = fieldMap.get(fieldName);
+    if (fieldMeta && value !== void 0) {
+      value = serializeFieldValue(value, fieldMeta);
+    }
+    keyInput[fieldName] = value;
+  }
+  const { pk, sk } = resolveSegmentedKey(
+    primaryKey.segmented,
+    keyInput,
+    `${modelClass.name} primary key`
+  );
+  return { pk, sk: sk ?? "" };
+}
+function buildUpdateInput(modelClass, entity, changes, options) {
+  const meta = MetadataRegistry.get(modelClass);
+  if (!meta.primaryKey) {
+    throw new Error(
+      `No primary key defined for '${modelClass.name}'. Ensure the model has a static \`keys = key(...)\` definition.`
+    );
+  }
+  const tableName = TableMapping.resolve(meta.tableName);
+  const fieldMap = new Map(
+    meta.fields.map((f) => [f.propertyName, f])
+  );
+  for (const fieldName of Object.keys(changes)) {
+    const fieldMeta = fieldMap.get(fieldName);
+    if (fieldMeta?.options?.readonly) {
+      throw new Error(
+        `Cannot update readonly field '${fieldName}' on '${modelClass.name}'. Readonly fields can only be set during put.`
+      );
+    }
+  }
+  const { pk, sk } = resolveUpdateKey(
+    modelClass,
+    meta.primaryKey,
+    entity,
+    fieldMap
+  );
+  const serializedChanges = {};
+  for (const [fieldName, value] of Object.entries(changes)) {
+    const fieldMeta = fieldMap.get(fieldName);
+    if (fieldMeta && value !== void 0) {
+      serializedChanges[fieldName] = serializeFieldValue(value, fieldMeta);
+    } else {
+      serializedChanges[fieldName] = value;
+    }
+  }
+  const embeddedFieldNames = new Set(
+    meta.embeddedFields.map((e) => e.propertyName)
+  );
+  const updateResult = buildUpdateExpression(serializedChanges, embeddedFieldNames);
+  const names = { ...updateResult.names };
+  const values = { ...updateResult.values };
+  let conditionExpression;
+  if (options?.condition) {
+    const condResult = buildConditionExpression(options.condition);
+    conditionExpression = condResult.expression;
+    Object.assign(names, condResult.names);
+    Object.assign(values, condResult.values);
+  }
+  const updateInput = {
+    TableName: tableName,
+    Key: {
+      PK: pk,
+      SK: sk
+    },
+    UpdateExpression: updateResult.expression,
+    ExpressionAttributeNames: names
+  };
+  if (Object.keys(values).length > 0) {
+    updateInput.ExpressionAttributeValues = values;
+  }
+  if (conditionExpression) {
+    updateInput.ConditionExpression = conditionExpression;
+  }
+  return updateInput;
+}
+function serializeChanges(modelClass, changes) {
+  const meta = MetadataRegistry.get(modelClass);
+  const fieldMap = new Map(meta.fields.map((f) => [f.propertyName, f]));
+  const out = {};
+  for (const [name, value] of Object.entries(changes)) {
+    const fieldMeta = fieldMap.get(name);
+    out[name] = fieldMeta && value !== void 0 ? serializeFieldValue(value, fieldMeta) : value;
+  }
+  return out;
+}
+async function executeUpdate(modelClass, entity, changes, options) {
+  const updateInput = buildUpdateInput(modelClass, entity, changes, options);
+  const wantsOld = ChangeCaptureRegistry.wantsOldImage(modelClass);
+  const result = await ClientManager.getExecutor().update(
+    updateInput,
+    wantsOld ? { returnOldImage: true } : void 0
+  );
+  if (ChangeCaptureRegistry.hasSubscribers()) {
+    const oldItem = result.oldItem;
+    const keys = { pk: String(updateInput.Key.PK), sk: String(updateInput.Key.SK ?? "") };
+    const changedAttrs = serializeChanges(modelClass, changes);
+    const newItem = {
+      ...oldItem ?? { PK: keys.pk, SK: keys.sk },
+      ...changedAttrs
+    };
+    captureWrite({
+      table: updateInput.TableName,
+      model: modelClass.name,
+      op: "update",
+      keys,
+      newItem,
+      ...oldItem ? { oldItem } : {}
+    });
+  }
+}
+
+// src/operations/delete.ts
+function buildDeleteInput(modelClass, keyObj, options) {
+  const meta = MetadataRegistry.get(modelClass);
+  if (!meta.primaryKey) {
+    throw new Error(
+      `No primary key defined for '${modelClass.name}'. Ensure the model has a static \`keys = key(...)\` definition.`
+    );
+  }
+  const tableName = TableMapping.resolve(meta.tableName);
+  const fieldMap = new Map(
+    meta.fields.map((f) => [f.propertyName, f])
+  );
+  const keyInput = {};
+  for (const fieldName of meta.primaryKey.inputFieldNames) {
+    let value = keyObj[fieldName];
+    const fieldMeta = fieldMap.get(fieldName);
+    if (fieldMeta && value !== void 0) {
+      value = serializeFieldValue(value, fieldMeta);
+    }
+    keyInput[fieldName] = value;
+  }
+  const { pk, sk } = resolveSegmentedKey(
+    meta.primaryKey.segmented,
+    keyInput,
+    `${modelClass.name} primary key`
+  );
+  const deleteInput = {
+    TableName: tableName,
+    Key: {
+      PK: pk,
+      SK: sk ?? ""
+    }
+  };
+  if (options?.condition) {
+    const condResult = buildConditionExpression(options.condition);
+    deleteInput.ConditionExpression = condResult.expression;
+    if (Object.keys(condResult.names).length > 0) {
+      deleteInput.ExpressionAttributeNames = condResult.names;
+    }
+    if (Object.keys(condResult.values).length > 0) {
+      deleteInput.ExpressionAttributeValues = condResult.values;
+    }
+  }
+  return deleteInput;
+}
+async function executeDelete(modelClass, keyObj, options) {
+  const deleteInput = buildDeleteInput(modelClass, keyObj, options);
+  const wantsOld = ChangeCaptureRegistry.wantsOldImage(modelClass);
+  const result = await ClientManager.getExecutor().delete(
+    deleteInput,
+    wantsOld ? { returnOldImage: true } : void 0
+  );
+  if (ChangeCaptureRegistry.hasSubscribers()) {
+    const oldItem = result.oldItem;
+    captureWrite({
+      table: deleteInput.TableName,
+      model: modelClass.name,
+      op: "delete",
+      keys: { pk: String(deleteInput.Key.PK), sk: String(deleteInput.Key.SK ?? "") },
+      ...oldItem ? { oldItem } : {}
+    });
+  }
+}
+
+// src/runtime/same-key-collapse.ts
+function collapseSameKey(items, view) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    const sig = view.keySignature(item);
+    const bucket = groups.get(sig);
+    if (bucket === void 0) groups.set(sig, [item]);
+    else bucket.push(item);
+  }
+  const replacement = /* @__PURE__ */ new Map();
+  const dropped = /* @__PURE__ */ new Set();
+  for (const bucket of groups.values()) {
+    if (bucket.length === 1) continue;
+    const kinds = new Set(bucket.map((it) => view.kind(it)));
+    if (kinds.has("Delete") && kinds.has("Put")) {
+      for (const it of bucket) dropped.add(it);
+      continue;
+    }
+    if (kinds.has("Put") && kinds.has("Update")) {
+      throw new Error(
+        `Contract runtime: a derived counter (\`increment\`) resolves to the SAME item as the entity write at runtime (the call-time key values made an aliased target coincide with the written row). A Put+Update on one transaction item is unsupported \u2014 DynamoDB rejects touching one key twice, and collapsing it would silently drop the increment. A \`w.increment(...)\` must target a DIFFERENT row (e.g. a parent aggregate's counter); to maintain a counter ON the written entity, write the field as part of the entity itself, not via a derived counter onto its own row.`
+      );
+    }
+    if (kinds.size === 1 && kinds.has("Update")) {
+      replacement.set(bucket[0], view.mergeAdds(bucket));
+      for (const it of bucket.slice(1)) dropped.add(it);
+      continue;
+    }
+    if (kinds.size === 1 && (kinds.has("Put") || kinds.has("Delete"))) {
+      for (const it of bucket.slice(1)) dropped.add(it);
+      continue;
+    }
+    throw new Error(
+      `Contract runtime: ${bucket.length} transaction items resolve to the same physical row with an unsupported op combination (${[...kinds].sort().join("+")}). A TransactWriteItems may not touch one key twice; this collision is not a known collapse shape (self-row Put/Delete de-dup, swap no-op, or symmetric counter ADDs), so it is rejected rather than silently collapsed.`
+    );
+  }
+  const out = [];
+  for (const item of items) {
+    if (dropped.has(item)) continue;
+    out.push(replacement.get(item) ?? item);
+  }
+  return out;
+}
+
+// src/runtime/transaction-commit.ts
+var MAX_TRANSACT_ITEMS = 25;
+var execItemCollapseView = {
+  kind: execItemKind,
+  keySignature: execItemKeySignature,
+  mergeAdds: mergeAddUpdates
+};
+function collapseSameKeyItems(items) {
+  return collapseSameKey(items, execItemCollapseView);
+}
+async function commitTransaction(items, options = {}) {
+  const collapsed = collapseSameKeyItems(items);
+  if (collapsed.length === 0) return collapsed;
+  if (collapsed.length > MAX_TRANSACT_ITEMS) {
+    throw options.limitError ? options.limitError(collapsed.length) : new Error(
+      `Transaction exceeds DynamoDB limit of ${MAX_TRANSACT_ITEMS} items`
+    );
+  }
+  await ClientManager.getExecutor().transactWrite(collapsed);
+  captureTransactItems(collapsed, options.modelBySignature ?? EMPTY_MODEL_MAP);
+  return collapsed;
+}
+var EMPTY_MODEL_MAP = /* @__PURE__ */ new Map();
+function captureTransactItems(items, modelBySignature) {
+  if (!ChangeCaptureRegistry.hasSubscribers()) return;
+  for (const item of items) {
+    if ("ConditionCheck" in item) continue;
+    captureWrite(captureMetaForItem(item, modelBySignature));
+  }
+}
+function captureMetaForItem(item, modelBySignature) {
+  const model = modelBySignature.get(execItemKeySignature(item));
+  const labelled = model !== void 0 ? { model } : {};
+  if ("Put" in item) {
+    const Item = item.Put.Item;
+    return {
+      table: item.Put.TableName,
+      ...labelled,
+      op: "put",
+      keys: { pk: String(Item.PK), sk: String(Item.SK ?? "") },
+      newItem: Item
+    };
+  }
+  if ("Update" in item) {
+    return {
+      table: item.Update.TableName,
+      ...labelled,
+      op: "update",
+      keys: { pk: String(item.Update.Key.PK), sk: String(item.Update.Key.SK ?? "") }
+    };
+  }
+  return {
+    table: item.Delete.TableName,
+    ...labelled,
+    op: "delete",
+    keys: { pk: String(item.Delete.Key.PK), sk: String(item.Delete.Key.SK ?? "") }
+  };
+}
+function execItemKeySignature(item) {
+  const part = (rec) => `${String(rec?.PK ?? "")}#${String(rec?.SK ?? "")}`;
+  if ("Put" in item) return `${item.Put.TableName}#${part(item.Put.Item)}`;
+  if ("Update" in item) return `${item.Update.TableName}#${part(item.Update.Key)}`;
+  if ("Delete" in item) return `${item.Delete.TableName}#${part(item.Delete.Key)}`;
+  return `${item.ConditionCheck.TableName}#${part(item.ConditionCheck.Key)}`;
+}
+function execItemKind(item) {
+  if ("Put" in item) return "Put";
+  if ("Update" in item) return "Update";
+  if ("Delete" in item) return "Delete";
+  return "ConditionCheck";
+}
+function mergeAddUpdates(updates) {
+  const first = updates[0];
+  if (!("Update" in first)) {
+    throw new Error("Contract runtime: mergeAddUpdates received a non-Update item.");
+  }
+  const deltas = /* @__PURE__ */ new Map();
+  for (const it of updates) {
+    if (!("Update" in it)) {
+      throw new Error("Contract runtime: cannot merge a non-Update item into an ADD.");
+    }
+    const names2 = it.Update.ExpressionAttributeNames ?? {};
+    const values2 = it.Update.ExpressionAttributeValues ?? {};
+    for (const [namePlaceholder, attr] of Object.entries(names2)) {
+      const valuePlaceholder = `:${namePlaceholder.slice(1)}`;
+      const delta = values2[valuePlaceholder];
+      if (typeof delta !== "number") {
+        throw new Error(
+          `Contract runtime: cannot merge same-key counter updates \u2014 an ADD delta on '${attr}' is not numeric.`
+        );
+      }
+      deltas.set(attr, (deltas.get(attr) ?? 0) + delta);
+    }
+  }
+  const names = {};
+  const values = {};
+  const clauses = [];
+  let i = 0;
+  for (const [attr, delta] of deltas) {
+    names[`#a${i}`] = attr;
+    values[`:a${i}`] = delta;
+    clauses.push(`#a${i} :a${i}`);
+    i++;
+  }
+  const merged = {
+    TableName: first.Update.TableName,
+    Key: first.Update.Key,
+    UpdateExpression: `ADD ${clauses.join(", ")}`,
+    ExpressionAttributeNames: names,
+    ExpressionAttributeValues: values
+  };
+  return { Update: merged };
+}
+
+// src/operations/transaction.ts
+var MODEL_CLASS_KEY = /* @__PURE__ */ Symbol.for("graphddb.modelClass");
+function attachModelClass(modelStatic, modelClass) {
+  Object.defineProperty(modelStatic, MODEL_CLASS_KEY, {
+    value: modelClass,
+    enumerable: false,
+    configurable: false,
+    writable: false
+  });
+  return modelStatic;
+}
+function resolveModelClass(model) {
+  const modelClass = model[MODEL_CLASS_KEY];
+  if (!modelClass) {
+    throw new Error(
+      "Invalid model reference. Use ModelStatic from DDBModel.asModel()."
+    );
+  }
+  return modelClass;
+}
+var TransactionContext = class {
+  items = [];
+  captureMeta = [];
+  get itemCount() {
+    return this.items.length;
+  }
+  put(model, item, options) {
+    this.assertWithinLimit();
+    const modelClass = resolveModelClass(model);
+    const putInput = buildPutInput(modelClass, item, options);
+    this.items.push({ Put: putInput });
+    this.captureMeta.push({
+      modelName: modelClass.name,
+      op: "put",
+      table: putInput.TableName,
+      keys: { pk: String(putInput.Item.PK), sk: String(putInput.Item.SK ?? "") },
+      newItem: putInput.Item
+    });
+  }
+  update(model, entity, changes, options) {
+    this.assertWithinLimit();
+    const modelClass = resolveModelClass(model);
+    const updateInput = buildUpdateInput(modelClass, entity, changes, options);
+    this.items.push({ Update: updateInput });
+    this.captureMeta.push({
+      modelName: modelClass.name,
+      op: "update",
+      table: updateInput.TableName,
+      keys: { pk: String(updateInput.Key.PK), sk: String(updateInput.Key.SK ?? "") }
+    });
+  }
+  delete(model, key2, options) {
+    this.assertWithinLimit();
+    const modelClass = resolveModelClass(model);
+    const deleteInput = buildDeleteInput(modelClass, key2, options);
+    this.items.push({ Delete: deleteInput });
+    this.captureMeta.push({
+      modelName: modelClass.name,
+      op: "delete",
+      table: deleteInput.TableName,
+      keys: { pk: String(deleteInput.Key.PK), sk: String(deleteInput.Key.SK ?? "") }
+    });
+  }
+  /**
+   * Add a read-only `ConditionCheck` assertion on a keyed item (issue #81). The
+   * item is **not** mutated; the `options.condition` (e.g.
+   * `{ attributeExists: 'PK' }` to require the row exists) is asserted, and a
+   * failed assertion cancels the **whole** `TransactWriteItems` atomically. This
+   * is the foundation for referential-integrity derivation (proposal: `requires
+   * <Entity> exists`). A ConditionCheck emits no change-capture record (it writes
+   * nothing).
+   *
+   * @throws if `options.condition` is missing — a ConditionCheck without an
+   *   assertion is meaningless.
+   */
+  conditionCheck(model, key2, options) {
+    if (!options || !options.condition) {
+      throw new Error(
+        "TransactionContext.conditionCheck requires a `condition` (the read-only assertion it makes); e.g. `{ condition: { attributeExists: 'PK' } }`."
+      );
+    }
+    this.assertWithinLimit();
+    const modelClass = resolveModelClass(model);
+    const { TableName, Key } = buildDeleteInput(modelClass, key2);
+    const cond = buildConditionExpression(options.condition);
+    const check = {
+      TableName,
+      Key,
+      ConditionExpression: cond.expression
+    };
+    if (Object.keys(cond.names).length > 0) {
+      check.ExpressionAttributeNames = cond.names;
+    }
+    if (Object.keys(cond.values).length > 0) {
+      check.ExpressionAttributeValues = cond.values;
+    }
+    this.items.push({ ConditionCheck: check });
+  }
+  /** @internal */
+  getTransactItems() {
+    return this.items;
+  }
+  /** @internal — capture descriptors for the write-capture seam (issue #72). */
+  getCaptureMeta() {
+    return this.captureMeta;
+  }
+  assertWithinLimit() {
+    if (this.items.length >= MAX_TRANSACT_ITEMS) {
+      throw new Error(
+        `Transaction exceeds DynamoDB limit of ${MAX_TRANSACT_ITEMS} items`
+      );
+    }
+  }
+};
+async function executeTransaction(fn) {
+  const tx = new TransactionContext();
+  await fn(tx);
+  const transactItems = tx.getTransactItems();
+  if (transactItems.length === 0) {
+    return;
+  }
+  const modelBySignature = /* @__PURE__ */ new Map();
+  for (const meta of tx.getCaptureMeta()) {
+    if (meta.modelName) {
+      modelBySignature.set(
+        `${meta.table}#${meta.keys.pk}#${meta.keys.sk}`,
+        meta.modelName
+      );
+    }
+  }
+  await commitTransaction(transactItems, {
+    modelBySignature
+  });
+}
+
+export {
+  isColumn,
+  createColumnMap,
+  isKeySegment,
+  k,
+  segmentFieldNames,
+  key,
+  gsi,
+  Linter,
+  noScanRule,
+  requireLimitRule,
+  gsiAmbiguityRule,
+  resolveKey,
+  missingGsiRule,
+  relationDepthRule,
+  createDefaultLinter,
+  MetadataRegistry,
+  TableMapping,
+  pkTemplate,
+  skTemplate,
+  resolveSegmentedKey,
+  BATCH_GET_MAX_KEYS,
+  BATCH_WRITE_MAX_ITEMS,
+  DynamoExecutor,
+  ClientManager,
+  buildConditionExpression,
+  serializeFieldValue,
+  ChangeCaptureRegistry,
+  captureWrite,
+  buildPutInput,
+  executePut,
+  buildUpdateExpression,
+  attachHiddenKey,
+  buildUpdateInput,
+  executeUpdate,
+  buildDeleteInput,
+  executeDelete,
+  MAX_TRANSACT_ITEMS,
+  collapseSameKeyItems,
+  commitTransaction,
+  execItemKeySignature,
+  attachModelClass,
+  resolveModelClass,
+  TransactionContext,
+  executeTransaction
+};