graphddb 0.2.5 → 0.3.0

package/README.md

@@ -657,7 +657,12 @@ Relation traversal は、Entity 上に定義されたアクセスパスのみを
   （`entityWrites`: 参照整合性、一意性、edge effect、派生カウンタ、outbox event、冪等性）を
   一度宣言すると、`mutation` が1つ以上の write fragment を合成し、コンパイラがそれらを単一の
   atomic な `TransactWriteItems` にマージする。すべての書き込みパスは1つの共有された
-  `commitTransaction` オーケストレーションを経由する。
+  `commitTransaction` オーケストレーションを経由する。**リレーション維持アクセスパス**
+  （Epic #118）はこれを拡張する: リレーションの `write.maintainedOn` やスカラ `@aggregate`
+  フィールドが、source エンティティのライフサイクルに同期して *別の* 行を維持する —— 射影された
+  **snapshot**（`SET`）、上限付き **collection**（`list_append`）、スカラ **counter**
+  （`@aggregate` `count()` → atomic `ADD ±1`）—— を source write と同一の atomic transaction に
+  合成する（[aggregate-counter](./examples/aggregate-counter/) 例を参照）。
 - **[Opt-in class hydration](./docs/class-hydration.md)** —— `options.hydrate` ファクトリを
   渡すと、read 結果をデフォルトの Typed Plain Object ではなく、ホスト言語のドメインオブジェクトに
   ロードできる。ホスト専用で、bridge SSoT にシリアライズされることはない。Phase 1
@@ -689,6 +694,8 @@ Relation traversal は、Entity 上に定義されたアクセスパスのみを
 |---------|-------------|
 | [user-permissions](./examples/user-permissions/) | Single Table Design でユーザー・グループ・パーミッションを管理する。隣接リスト、転置インデックス、relation traversal、`explain` を含む。 |
 | [aggregate-tree-pattern](./examples/aggregate-tree-pattern/) | CDC emulator で駆動される差分的なツリー集計（`siteScoreAverage`）: dirty 伝播、throttle 付き sweep、再計算。 |
+| [embedded-snapshot-pattern](./examples/embedded-snapshot-pattern/) | リレーションを **維持アクセスパス** として扱う（Epic #118）: `pattern: 'embeddedSnapshot'` のリレーションが、source write と同一の atomic transaction で、非正規化された collection / snapshot を owner 行に同期維持する。 |
+| [aggregate-counter](./examples/aggregate-counter/) | RFC §5.2 の `@aggregate` **counter**: `ThreadPost.created`/`removed` のライフサイクルが、source write と同一の `TransactWriteItems` 内で atomic な `ADD ±1` により `ThreadCounter.postCount` を同期維持する。 |
 
 ## ✨ Features
 
@@ -703,6 +710,7 @@ Relation traversal は、Entity 上に定義されたアクセスパスのみを
 - 構造化 segment キー（`k` タグ）: partial key は segment 境界で `begins_with` にコンパイルされる
 - 説明可能な実行計画
 - Relation（hasMany, belongsTo, hasOne, depth 制限, traversal）
+- 維持アクセスパス（Epic #118）: `pattern: 'embeddedSnapshot'` のリレーションが非正規化された collection / 単一行 snapshot を owner 行に同期維持し、`@aggregate` `count()` カウンタが atomic な `ADD ±1` で同期する。いずれも source write の atomic transaction に合成される（`maintainedOn` cross-entity トリガ、関数形 `projection`）。同期（`updateMode: 'mutation'`）の維持は TS / Python 両方で動作（conformance 検証済み）。stream / trim / `max()` / `materializedView` / `sparseView` は後続フェーズ
 - BatchGet 最適化
 - 並列 relation 実行（独立したサブクエリ、BatchGet チャンク、ネストした解決を上限付きの
   並列度で同時にディスパッチ）

package/dist/{chunk-4TYK3AV6.js → chunk-6AIAHP3A.js}

@@ -411,6 +411,437 @@ var relationDepthRule = {
   }
 };
 
+// src/linter/rules/same-partition-preset.ts
+var samePartitionPresetRule = {
+  id: "same-partition-preset",
+  severity: "error",
+  check(metadata, registry) {
+    const results = [];
+    for (const relation of metadata.relations) {
+      if (relation.options?.pattern !== "samePartition") continue;
+      results.push(...checkRelation(metadata, relation, registry));
+    }
+    return results;
+  }
+};
+function err(metadata, relation, message) {
+  return {
+    ruleId: "same-partition-preset",
+    severity: "error",
+    message: `Relation '${relation.propertyName}' on entity '${metadata.prefix}' declares pattern 'samePartition' but ${message}`,
+    entity: metadata.prefix,
+    field: relation.propertyName
+  };
+}
+function checkRelation(metadata, relation, registry) {
+  if (relation.type !== "hasMany") {
+    return [
+      err(
+        metadata,
+        relation,
+        `is a '${relation.type}'. 'samePartition' lowers a parent\u2192children collection read (begins_with on a segmented sort key) and is only valid on @hasMany.`
+      )
+    ];
+  }
+  const results = [];
+  const maintenanceOptions = ["read", "write", "projection"].filter(
+    (k2) => relation.options?.[k2] !== void 0
+  );
+  if (maintenanceOptions.length > 0) {
+    results.push(
+      err(
+        metadata,
+        relation,
+        `also sets [${maintenanceOptions.join(", ")}]. 'samePartition' has no maintained materialisation \u2014 children are read live by begins_with, so it carries no read/write/projection effect. Drop these options (or use a maintained preset such as 'embeddedSnapshot').`
+      )
+    );
+  }
+  const targetFields = Object.keys(relation.keyBinding);
+  if (targetFields.length === 0) {
+    results.push(
+      err(metadata, relation, `has an empty keyBinding; nothing to lower.`)
+    );
+    return results;
+  }
+  let targetMeta;
+  try {
+    const targetClass = relation.targetFactory();
+    targetMeta = registry.get(targetClass);
+  } catch {
+    results.push(
+      err(
+        metadata,
+        relation,
+        `targets an entity that is not registered in MetadataRegistry.`
+      )
+    );
+    return results;
+  }
+  let resolved;
+  try {
+    resolved = resolveKey(targetFields, targetMeta);
+  } catch {
+    results.push(
+      err(
+        metadata,
+        relation,
+        `binds [${targetFields.join(", ")}] on target '${targetMeta.prefix}', which matches no access pattern. A same-partition relation must bind a contiguous prefix of the target's primary key.`
+      )
+    );
+    return results;
+  }
+  if (resolved.type !== "pk") {
+    results.push(
+      err(
+        metadata,
+        relation,
+        `binds [${targetFields.join(", ")}] to a ${resolved.type.toUpperCase()} on target '${targetMeta.prefix}'. A GSI is a different partition; 'samePartition' requires the binding to resolve on the target's primary key (same PK, segmented-SK begins_with).`
+      )
+    );
+    return results;
+  }
+  if (!resolved.partial) {
+    results.push(
+      err(
+        metadata,
+        relation,
+        `binds the target's full primary key on '${targetMeta.prefix}', which is a point read of a single item, not a child collection. 'samePartition' requires a partial key \u2014 the parent fields fully supply the PK and a proper prefix of the segmented SK, leaving a begins_with boundary for the children.`
+      )
+    );
+  }
+  return results;
+}
+
+// src/linter/rules/maintenance-shared.ts
+function isMaintainedRelation(relation) {
+  const triggers = relation.options?.write?.maintainedOn;
+  return Array.isArray(triggers) && triggers.length > 0;
+}
+function maintainedRelations(metadata) {
+  return metadata.relations.filter(isMaintainedRelation);
+}
+function logicalName(metadata) {
+  return metadata.prefix.endsWith("#") ? metadata.prefix.slice(0, -1) : metadata.prefix;
+}
+function payloadAttributes(meta) {
+  const attrs = /* @__PURE__ */ new Set();
+  for (const f of meta.fields) attrs.add(f.propertyName);
+  if (meta.primaryKey) {
+    for (const f of segmentFieldNames(meta.primaryKey.segmented.pkSegments)) {
+      attrs.add(f);
+    }
+    for (const f of segmentFieldNames(meta.primaryKey.segmented.skSegments)) {
+      attrs.add(f);
+    }
+  }
+  for (const gsi2 of meta.gsiDefinitions) {
+    for (const f of segmentFieldNames(gsi2.segmented.pkSegments)) attrs.add(f);
+    for (const f of segmentFieldNames(gsi2.segmented.skSegments)) attrs.add(f);
+  }
+  return attrs;
+}
+function isPayloadRooted(value) {
+  return value.startsWith("$.input.") || value.startsWith("$.entity.");
+}
+function projectionSourceAttribute(value) {
+  const path = typeof value === "string" ? value : value.path;
+  if (typeof value === "string") {
+    if (!isPayloadRooted(path)) return path;
+  } else if (!isPayloadRooted(path)) {
+    return null;
+  }
+  const stripped = path.replace(/^\$\.(input|entity)\./, "");
+  return stripped.split(".")[0] ?? stripped;
+}
+function projectionEntries(projection) {
+  return projection ? Object.entries(projection) : [];
+}
+
+// src/linter/rules/missing-context.ts
+var missingContextRule = {
+  id: "missing-context",
+  severity: "error",
+  check(metadata, registry) {
+    const results = [];
+    for (const relation of maintainedRelations(metadata)) {
+      results.push(...checkRelation2(metadata, relation, registry));
+    }
+    return results;
+  }
+};
+function err2(metadata, relation, message) {
+  return {
+    ruleId: "missing-context",
+    severity: "error",
+    message: `Maintained relation '${relation.propertyName}' on '${logicalName(metadata)}' ${message}`,
+    entity: metadata.prefix,
+    field: relation.propertyName
+  };
+}
+function checkRelation2(metadata, relation, registry) {
+  let sourceMeta;
+  try {
+    sourceMeta = registry.get(relation.targetFactory());
+  } catch {
+    return [];
+  }
+  const sourceName = logicalName(sourceMeta);
+  const payload = payloadAttributes(sourceMeta);
+  const available = `available: ${[...payload].sort().map((f) => `'${f}'`).join(", ")}`;
+  const results = [];
+  for (const sourceField of Object.keys(relation.keyBinding)) {
+    if (!payload.has(sourceField)) {
+      results.push(
+        err2(
+          metadata,
+          relation,
+          `resolves its destination row from source field '${sourceField}', but the source entity '${sourceName}' carries no such attribute on its write payload (${available}). Phase 1 maintenance is payload \u540C\u68B1 only (no write-time fetch) \u2014 include '${sourceField}' on '${sourceName}' or bind a key field it does carry.`
+        )
+      );
+    }
+  }
+  for (const [attr, value] of projectionEntries(relation.options?.projection)) {
+    const path = typeof value === "string" ? value : value.path;
+    const srcAttr = projectionSourceAttribute(value);
+    if (srcAttr === null || typeof value !== "string" && !isPayloadRooted(path)) {
+      results.push(
+        err2(
+          metadata,
+          relation,
+          `projects '${attr}' from '${path}', which is not a payload-rooted source path (\`$.input.*\` / \`$.entity.*\`). Phase 1 maintenance projects only from the source payload (payload \u540C\u68B1); there is no fetch / re-projection.`
+        )
+      );
+      continue;
+    }
+    if (!payload.has(srcAttr)) {
+      results.push(
+        err2(
+          metadata,
+          relation,
+          `projects '${attr}' from source attribute '${srcAttr}', but the source entity '${sourceName}' carries no such attribute on its write payload (${available}). Phase 1 maintenance is payload \u540C\u68B1 only (no write-time fetch / re-projection) \u2014 an attribute the source row does not carry cannot be projected.`
+        )
+      );
+    }
+  }
+  return results;
+}
+
+// src/linter/rules/embedded-snapshot-size.ts
+var ITEM_LIMIT_BYTES = 400 * 1024;
+var SOFT_BUDGET_BYTES = ITEM_LIMIT_BYTES / 2;
+var DEFAULT_STRING_BYTES = 256;
+var ATTR_NAME_OVERHEAD_BYTES = 16;
+var embeddedSnapshotSizeRule = {
+  id: "400kb",
+  severity: "warning",
+  check(metadata, _registry) {
+    const results = [];
+    for (const relation of maintainedRelations(metadata)) {
+      const result = checkRelation3(metadata, relation);
+      if (result) results.push(result);
+    }
+    return results;
+  }
+};
+function estimateItemBytes(relation) {
+  let bytes = 0;
+  for (const [attr, value] of projectionEntries(relation.options?.projection)) {
+    bytes += ATTR_NAME_OVERHEAD_BYTES + attr.length;
+    bytes += attributeValueBytes(value);
+  }
+  return bytes;
+}
+function attributeValueBytes(value) {
+  if (typeof value !== "string" && value.op === "preview") {
+    const [n] = value.args;
+    if (typeof n === "number" && Number.isFinite(n)) return n;
+  }
+  return DEFAULT_STRING_BYTES;
+}
+function checkRelation3(metadata, relation) {
+  const itemBytes = estimateItemBytes(relation);
+  if (itemBytes === 0) return null;
+  const isCollection = relation.type === "hasMany";
+  const maxItems = relation.options?.read?.maxItems;
+  if (isCollection && maxItems === void 0) return null;
+  const count = isCollection ? maxItems : 1;
+  const estimate = itemBytes * count;
+  const shape = isCollection ? `${count} item(s) \xD7 ~${itemBytes} B` : `~${itemBytes} B snapshot`;
+  if (estimate >= ITEM_LIMIT_BYTES) {
+    return {
+      ruleId: "400kb",
+      severity: "error",
+      message: `Maintained relation '${relation.propertyName}' on '${logicalName(metadata)}' materializes ${shape} \u2248 ${estimate} B onto the owner row, which meets or exceeds DynamoDB's 400 KB item limit (${ITEM_LIMIT_BYTES} B). The maintenance write would fail once the collection fills \u2014 reduce \`read.maxItems\` or the projected attributes (e.g. tighter \`preview(n)\` bounds).`,
+      entity: metadata.prefix,
+      field: relation.propertyName
+    };
+  }
+  if (estimate >= SOFT_BUDGET_BYTES) {
+    return {
+      ruleId: "400kb",
+      severity: "warning",
+      message: `Maintained relation '${relation.propertyName}' on '${logicalName(metadata)}' materializes ${shape} \u2248 ${estimate} B onto the owner row, over half of DynamoDB's 400 KB item limit (${ITEM_LIMIT_BYTES} B). Little headroom remains for the rest of the item \u2014 consider a tighter \`read.maxItems\` / projection.`,
+      entity: metadata.prefix,
+      field: relation.propertyName
+    };
+  }
+  return null;
+}
+
+// src/linter/rules/hot-partition.ts
+var HOT_TRIGGER_FANIN = 2;
+var hotPartitionRule = {
+  id: "hot-partition",
+  severity: "warning",
+  check(metadata, _registry) {
+    const results = [];
+    const maintained = maintainedRelations(metadata);
+    for (const relation of maintained) {
+      if (relation.type !== "hasMany") continue;
+      if (relation.options?.read?.maxItems === void 0) {
+        results.push(unboundedWarning(metadata, relation));
+      }
+    }
+    const byTrigger = /* @__PURE__ */ new Map();
+    for (const relation of maintained) {
+      for (const trigger of relation.options?.write?.maintainedOn ?? []) {
+        const bucket = byTrigger.get(trigger);
+        if (bucket) bucket.push(relation.propertyName);
+        else byTrigger.set(trigger, [relation.propertyName]);
+      }
+    }
+    for (const [trigger, props] of byTrigger) {
+      if (props.length > HOT_TRIGGER_FANIN) {
+        results.push(fanInWarning(metadata, trigger, props));
+      }
+    }
+    return results;
+  }
+};
+function unboundedWarning(metadata, relation) {
+  return {
+    ruleId: "hot-partition",
+    severity: "warning",
+    message: `Maintained collection '${relation.propertyName}' on '${logicalName(metadata)}' has no \`read.maxItems\` bound: every maintained source row appends to the same owner ("root") item, so that single partition takes unbounded write traffic and the item trends toward the 400 KB limit. Declare a \`read.maxItems\` window (e.g. latest-N) or read the children from their own partition (\`samePartition\`) instead of inlining a snapshot.`,
+    entity: metadata.prefix,
+    field: relation.propertyName
+  };
+}
+function fanInWarning(metadata, trigger, props) {
+  return {
+    ruleId: "hot-partition",
+    severity: "warning",
+    message: `${props.length} maintained relations on '${logicalName(metadata)}' ([${props.map((p) => `'${p}'`).join(", ")}]) all fire on trigger '${trigger}', concentrating that many maintenance writes onto the single owner ("root") row in one mutation. This amplifies per-source-row write cost on one partition \u2014 consider splitting the maintained shapes across rows / partitions.`,
+    entity: metadata.prefix
+  };
+}
+
+// src/linter/rules/fan-out.ts
+var MAX_MAINTENANCE_HOPS = 1;
+var fanOutRule = {
+  id: "fan-out",
+  severity: "warning",
+  check(metadata, registry) {
+    const results = [];
+    for (const relation of maintainedRelations(metadata)) {
+      const point = checkDestinationFanOut(metadata, relation);
+      if (point) results.push(point);
+    }
+    const chain = maintenanceChain(metadata, registry, /* @__PURE__ */ new Set([modelKey(metadata)]));
+    if (chain.hops > MAX_MAINTENANCE_HOPS) {
+      results.push({
+        ruleId: "fan-out",
+        severity: "warning",
+        message: `Entity '${chain.root}' is the root of a maintenance chain ${chain.hops} hops deep, terminating at '${logicalName(metadata)}': a single '${chain.root}' lifecycle event cascades through ${chain.hops} maintenance writes \u2014 each maintained row is itself the trigger source of the next hop \u2014 until it reaches '${logicalName(metadata)}'. A multi-step maintenance fan-out amplifies one write into many; flatten the chain or move downstream hops to a stream (\`updateMode: 'stream'\`).`,
+        entity: metadata.prefix
+      });
+    }
+    return results;
+  }
+};
+function checkDestinationFanOut(metadata, relation) {
+  const ownerKeyFields = Object.values(relation.keyBinding);
+  if (ownerKeyFields.length === 0) return null;
+  let resolved;
+  try {
+    resolved = resolveKey(ownerKeyFields, metadata);
+  } catch {
+    return null;
+  }
+  const isPoint = !resolved.partial && (resolved.type === "pk" || resolved.type === "gsi" && resolved.unique);
+  if (isPoint) return null;
+  const shape = resolved.partial ? `a partial ${resolved.type.toUpperCase()} (a begins_with range of rows)` : `a non-unique ${resolved.type.toUpperCase()} (many matching rows)`;
+  return {
+    ruleId: "fan-out",
+    severity: "warning",
+    message: `Maintained relation '${relation.propertyName}' on '${logicalName(metadata)}' binds its destination row by [${ownerKeyFields.map((f) => `'${f}'`).join(", ")}], which resolves to ${shape} on '${logicalName(metadata)}'. A single source event then fans its maintenance write out across every matching destination row in one mutation (unbounded fan-out). Bind the destination's full primary key (or a unique GSI) so each source event maintains exactly one row.`,
+    entity: metadata.prefix,
+    field: relation.propertyName
+  };
+}
+function modelKey(metadata) {
+  return logicalName(metadata);
+}
+function maintenanceChain(metadata, registry, visited) {
+  const maintained = maintainedRelations(metadata);
+  if (maintained.length === 0) return { hops: 0, root: logicalName(metadata) };
+  let best = { hops: 0, root: logicalName(metadata) };
+  for (const relation of maintained) {
+    let targetMeta;
+    try {
+      targetMeta = registry.get(relation.targetFactory());
+    } catch {
+      continue;
+    }
+    const key2 = modelKey(targetMeta);
+    if (visited.has(key2)) continue;
+    const next = new Set(visited);
+    next.add(key2);
+    const upstream = maintenanceChain(targetMeta, registry, next);
+    if (1 + upstream.hops > best.hops) {
+      best = { hops: 1 + upstream.hops, root: upstream.root };
+    }
+  }
+  return best;
+}
+
+// src/linter/rules/multi-maintainer-same-row.ts
+var multiMaintainerSameRowRule = {
+  id: "multi-maintainer-same-row",
+  severity: "error",
+  check(metadata, _registry) {
+    const maintained = maintainedRelations(metadata);
+    if (maintained.length < 2) return [];
+    const owner = logicalName(metadata);
+    const groups = /* @__PURE__ */ new Map();
+    for (const relation of maintained) {
+      const rowKey = destinationRowKey(owner, relation);
+      for (const trigger of relation.options?.write?.maintainedOn ?? []) {
+        const groupKey = `${trigger} ${rowKey}`;
+        const group = groups.get(groupKey);
+        if (group) group.props.push(relation.propertyName);
+        else groups.set(groupKey, { trigger, props: [relation.propertyName] });
+      }
+    }
+    const results = [];
+    for (const { trigger, props } of groups.values()) {
+      if (props.length < 2) continue;
+      results.push({
+        ruleId: "multi-maintainer-same-row",
+        severity: "error",
+        message: `Maintained relations [${props.map((p) => `'${p}'`).join(", ")}] on '${owner}' all fire on trigger '${trigger}' and write the SAME destination row. Phase 1 maintenance is "1 mutation \xD7 1 target row = 1 effect" (\u8AD6\u70B92 = b): a single mutation cannot touch one row with ${props.length} maintain effects \u2014 DynamoDB rejects two writes to the same key in one TransactWriteItems (cf. #96). Merge the projections into one maintained relation, or split them onto distinct destination rows / triggers.`,
+        entity: metadata.prefix,
+        field: props[0]
+      });
+    }
+    return results;
+  }
+};
+function destinationRowKey(owner, relation) {
+  const parts = Object.entries(relation.keyBinding).map(([sourceField, ownerField]) => `${ownerField}=$.entity.${sourceField}`).sort();
+  return `${owner}#${parts.join("&")}`;
+}
+
 // src/linter/default-linter.ts
 function createDefaultLinter() {
   const linter = new Linter();
@@ -419,6 +850,12 @@ function createDefaultLinter() {
   linter.addRule(gsiAmbiguityRule);
   linter.addRule(missingGsiRule);
   linter.addRule(relationDepthRule);
+  linter.addRule(samePartitionPresetRule);
+  linter.addRule(missingContextRule);
+  linter.addRule(embeddedSnapshotSizeRule);
+  linter.addRule(hotPartitionRule);
+  linter.addRule(fanOutRule);
+  linter.addRule(multiMaintainerSameRowRule);
   return linter;
 }
 
@@ -426,8 +863,27 @@ function createDefaultLinter() {
 var MetadataRegistry = class {
   static store = /* @__PURE__ */ new Map();
   static _linter = createDefaultLinter();
+  /**
+   * A monotonically-increasing counter bumped on every change to the set of
+   * registered models ({@link register} / {@link clear}). It lets a consumer that
+   * caches a structure derived from the whole registry (e.g. the maintenance graph
+   * in `src/spec/mutation-command.ts`) detect that the registry has changed since
+   * the cache was built and rebuild — closing the silent-drop window where a model
+   * registered after a cache build would be invisible to it. Only the membership
+   * of {@link store} changes here; per-model lazy finalize ({@link finalize}) does
+   * not bump it (it adds no relations/triggers, so it cannot change the graph).
+   */
+  static _generation = 0;
+  /**
+   * The current registry generation (see {@link _generation}). A consumer caches
+   * the value it built against and rebuilds when it no longer matches.
+   */
+  static get generation() {
+    return this._generation;
+  }
   static register(target, metadata) {
     this.store.set(target, { ...metadata, _finalized: false });
+    this._generation++;
   }
   static get(target) {
     const meta = this.store.get(target);
@@ -466,6 +922,7 @@ var MetadataRegistry = class {
   static clear() {
     this.store.clear();
     this._linter = new Linter();
+    this._generation++;
   }
   static finalize(target, meta) {
     for (const name of Object.getOwnPropertyNames(target)) {
@@ -1858,14 +2315,14 @@ var MiddlewareRuntime = class {
    * is the host's responsibility — a hook recovering a `query` should return an
    * item / `null`, one recovering a `list` a `{ items, cursor }`.
    */
-  async runRequestError(ctx, err) {
+  async runRequestError(ctx, err3) {
     for (let i = this.chain.length - 1; i >= 0; i--) {
       const onError = this.chain[i].read?.onError;
       if (!onError) continue;
-      const recovered = await onError(ctx, err);
+      const recovered = await onError(ctx, err3);
       if (recovered !== void 0) return recovered;
     }
-    throw err;
+    throw err3;
   }
   /**
    * Drive ONE physical op (root read or any fan-out fetch) through R2 → send →
@@ -1905,14 +2362,14 @@ var MiddlewareRuntime = class {
         if (afterFetch) items = await afterFetch(ctx, items);
       }
       return items;
-    } catch (err) {
+    } catch (err3) {
       for (let i = this.chain.length - 1; i >= 0; i--) {
         const onError = this.chain[i].read?.op?.onError;
         if (!onError) continue;
-        const recovered = await onError(ctx, err);
+        const recovered = await onError(ctx, err3);
         if (recovered !== void 0) return recovered;
       }
-      throw err;
+      throw err3;
     }
   }
 };
@@ -1976,14 +2433,14 @@ var WriteRuntime = class {
    * short-circuits the chain); the value becomes the write's resolved value.
    * Otherwise the original error rethrows (symmetric with the read `onError`).
    */
-  async runWriteError(ctx, err) {
+  async runWriteError(ctx, err3) {
     for (let i = this.chain.length - 1; i >= 0; i--) {
       const onError = this.chain[i].write?.onError;
       if (!onError) continue;
-      const recovered = await onError(ctx, err);
+      const recovered = await onError(ctx, err3);
       if (recovered !== void 0) return recovered;
     }
-    throw err;
+    throw err3;
   }
   /** Build a W3/W4/W5 persist context (pure — no hooks run). */
   persistCtx(items, origins, transaction) {
@@ -2012,20 +2469,20 @@ var WriteRuntime = class {
         if (before) await before(ctx);
       }
       results = await send(ctx.items);
-    } catch (err) {
+    } catch (err3) {
       let recovered;
       let didRecover = false;
       for (let i = this.chain.length - 1; i >= 0; i--) {
         const onError = this.chain[i].write?.persist?.onError;
         if (!onError) continue;
-        const r = await onError(ctx, err);
+        const r = await onError(ctx, err3);
         if (r !== void 0) {
           recovered = r;
           didRecover = true;
           break;
         }
       }
-      if (!didRecover) throw err;
+      if (!didRecover) throw err3;
       results = recovered;
     }
     for (let i = this.chain.length - 1; i >= 0; i--) {
@@ -2246,8 +2703,8 @@ async function executeSingleWriteWithHooks(req, mw) {
     await mw.runWriteBefore(ctx);
     const change2 = await persistRewrittenWrite(req.modelClass, ctx, mw);
     await mw.runWriteAfter(ctx, change2);
-  } catch (err) {
-    await mw.runWriteError(ctx, err);
+  } catch (err3) {
+    await mw.runWriteError(ctx, err3);
   }
 }
 async function persistRewrittenWrite(modelClass, ctx, mw) {