graphddb 0.2.4 → 0.3.0

package/dist/{chunk-GCPEUPAA.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)) {
@@ -834,6 +1291,27 @@ var RetryingExecutor = class {
   }
 };
 
+// src/middleware/registry.ts
+var MiddlewareRegistry = class {
+  list = [];
+  /** Register a middleware (appended last — it runs last in FIFO `before*`). */
+  use(mw) {
+    this.list.push(mw);
+  }
+  /** Remove all registered middleware (teardown / tests). */
+  clear() {
+    this.list = [];
+  }
+  /**
+   * A point-in-time, registration-ordered snapshot. A read takes this once at
+   * entry (R1) and threads it down, so its hook set is stable for the whole read
+   * even if middleware is registered / cleared mid-flight.
+   */
+  snapshot() {
+    return this.list.slice();
+  }
+};
+
 // src/client/ClientManager.ts
 var ClientManager = class {
   static client = null;
@@ -853,6 +1331,15 @@ var ClientManager = class {
    * read at call time by the default {@link RetryingExecutor}.
    */
   static retryPolicy = null;
+  /**
+   * The host-runtime read-middleware registry (issue #50 / #138) — a process-wide
+   * ordered list of {@link Middleware}, the same global-config + injectable-seam
+   * pattern as {@link retryPolicy} / {@link executor}. Registered via
+   * {@link DDBModel.use} / {@link use}, snapshotted per read, and NEVER serialized
+   * (it never touches the planner / spec / `operations.json`, so the bridge #48 is
+   * unaffected). {@link reset} clears it.
+   */
+  static middleware = new MiddlewareRegistry();
   static setClient(client) {
     this.client = client;
     this.documentClient = null;
@@ -919,12 +1406,34 @@ var ClientManager = class {
   static getRetryPolicy() {
     return this.retryPolicy;
   }
+  /**
+   * Register a read {@link Middleware} (issue #50 / #138). Appended last, so its
+   * `before*` hooks run last (FIFO) and its `afterFetch` / `onError` hooks run
+   * first (LIFO). Mirrors {@link setRetryPolicy}; backs {@link DDBModel.use}.
+   */
+  static use(mw) {
+    this.middleware.use(mw);
+  }
+  /** Remove every registered read middleware (teardown / tests). Backs {@link DDBModel.clearMiddleware}. */
+  static clearMiddleware() {
+    this.middleware.clear();
+  }
+  /**
+   * A point-in-time, registration-ordered snapshot of the registered read
+   * middleware. A read takes this once at entry (R1) and threads it down, so the
+   * read's hook set stays stable even if middleware is registered / cleared
+   * mid-flight.
+   */
+  static getMiddleware() {
+    return this.middleware.snapshot();
+  }
   /** @internal — for testing only */
   static reset() {
     this.client = null;
     this.documentClient = null;
     this.executor = null;
     this.retryPolicy = null;
+    this.middleware.clear();
   }
 };
 
@@ -1440,6 +1949,69 @@ function serializeFieldValue(value, fieldMeta) {
   return value;
 }
 
+// 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/metadata/segments.ts
 var SEGMENT_DELIMITER = "#";
 function segmentComplete(segment, values) {
@@ -1579,6 +2151,34 @@ function missingGsiFields(gsi2, available) {
   return gsi2.inputFieldNames.filter((f) => available[f] === void 0);
 }
 
+// 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/capture/registry.ts
 var ChangeCaptureRegistryImpl = class {
   subscribers = /* @__PURE__ */ new Set();
@@ -1648,7 +2248,279 @@ function captureWrite(record) {
   ChangeCaptureRegistry.emit(record);
 }
 
-// src/operations/put.ts
+// src/middleware/runtime.ts
+function opKind(operation) {
+  return operation.type;
+}
+var MiddlewareRuntime = class {
+  /** The frozen, registration-ordered middleware snapshot for this read. */
+  chain;
+  /** The host-injected per-call context (`{}` when the read passed none). */
+  context;
+  constructor(chain, context) {
+    this.chain = chain;
+    this.context = context;
+  }
+  /** `true` when at least one middleware is registered for this read. */
+  get active() {
+    return this.chain.length > 0;
+  }
+  /**
+   * Build the request-level context (R1 / R4 / R5 share it). Pure — no hooks run
+   * — so a caller can create it up front and still reference it from R5 even if
+   * R1 throws mid-chain.
+   */
+  requestCtx(kind, model, params) {
+    return { kind, model, context: this.context, state: {}, params };
+  }
+  /**
+   * R1 — request entry, before key-resolution / plan. Builds the
+   * {@link ReadRequestCtx} then runs every `read.before` FIFO; a hook may mutate
+   * `ctx.params` and may `throw` to cancel the read. Returns the (possibly
+   * hook-mutated) ctx so the caller can re-read `params` and reuse the SAME ctx
+   * for R4 / R5 (shared `state`).
+   */
+  async runRequestBefore(kind, model, params) {
+    const ctx = this.requestCtx(kind, model, params);
+    for (const mw of this.chain) {
+      const before = mw.read?.before;
+      if (before) await before(ctx);
+    }
+    return ctx;
+  }
+  /**
+   * R4 — final hydrated, relation-merged result. Runs every `read.afterFetch`
+   * LIFO, threading each hook's return value into the next (onion), and returns
+   * the final (possibly replaced) result. `ctx` is the SAME object R1 produced,
+   * so a `before`/`afterFetch` pair shares `ctx.state`.
+   */
+  async runRequestAfter(ctx, result) {
+    let current = result;
+    for (let i = this.chain.length - 1; i >= 0; i--) {
+      const afterFetch = this.chain[i].read?.afterFetch;
+      if (afterFetch) current = await afterFetch(ctx, current);
+    }
+    return current;
+  }
+  /**
+   * R5 (request-level) — runs every `read.onError` LIFO. A hook may **recover**
+   * by RETURNING a non-`undefined` value: it becomes the read's resolved result
+   * in place of throwing, and the FIRST such hook (in LIFO order) wins and
+   * short-circuits the rest of the chain. If every hook declines (returns
+   * `undefined`/`void`), the original error rethrows — preserving the
+   * "failed read still rejects" default. (Proposal R5 + appendix A: onError may
+   * "rethrow / recover"; hooks are unrestricted.)
+   *
+   * The recovered value is returned as `T` (the read's result type); its shape
+   * 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, 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, err3);
+      if (recovered !== void 0) return recovered;
+    }
+    throw err3;
+  }
+  /**
+   * Drive ONE physical op (root read or any fan-out fetch) through R2 → send →
+   * R3, with R5 (op-level) on failure:
+   *
+   * 1. R2 (`read.op.before`, FIFO) — may mutate `ctx.operation`, may `throw`;
+   * 2. the caller's `send` runs against the (possibly mutated) operation;
+   * 3. R3 (`read.op.afterFetch`, LIFO) — transforms the raw items (onion);
+   * 4. on any throw from `send` (or R2 / R3), R5 (`read.op.onError`, LIFO) runs:
+   *    a hook may **recover** by RETURNING an `Item[]` (those become this op's
+   *    items and the pipeline continues); the FIRST hook that returns items wins
+   *    and short-circuits the chain. If none recovers, the original error
+   *    rethrows.
+   *
+   * Returns the (possibly R3-replaced, or R5-recovered) items. The `send` closure
+   * receives the final operation so a caller that built its operation from
+   * `ctx.operation` before this call still observes an R2 mutation (the caller
+   * MUST send `ctx.operation`, which this method passes through).
+   */
+  async runOp(operation, relationPath, model, send) {
+    const ctx = {
+      kind: opKind(operation),
+      model,
+      context: this.context,
+      state: {},
+      operation,
+      relationPath
+    };
+    try {
+      for (const mw of this.chain) {
+        const before = mw.read?.op?.before;
+        if (before) await before(ctx);
+      }
+      let items = await send(ctx.operation);
+      for (let i = this.chain.length - 1; i >= 0; i--) {
+        const afterFetch = this.chain[i].read?.op?.afterFetch;
+        if (afterFetch) items = await afterFetch(ctx, items);
+      }
+      return items;
+    } 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, err3);
+        if (recovered !== void 0) return recovered;
+      }
+      throw err3;
+    }
+  }
+};
+var NO_MIDDLEWARE = new MiddlewareRuntime([], {});
+var WriteRuntime = class {
+  chain;
+  context;
+  constructor(chain, context) {
+    this.chain = chain;
+    this.context = context;
+  }
+  /** `true` when at least one middleware is registered for this write. */
+  get active() {
+    return this.chain.length > 0;
+  }
+  /**
+   * `true` when at least one registered middleware sets a `write.after` (W2) hook.
+   * The single-op write path (issue #139) uses this to decide whether to request
+   * the pre-write image (`ReturnValues: ALL_OLD`) so W2 receives a real
+   * `{ oldImage, newImage }` rather than `{}` — the cost is paid only when a W2
+   * hook actually exists.
+   */
+  get hasWriteAfter() {
+    return this.chain.some((mw) => mw.write?.after !== void 0);
+  }
+  /**
+   * Build a W1/W2/W5 logical-write context (pure — no hooks run). The caller can
+   * create it up front and reuse the SAME object across W1 → W2 / W5 (shared
+   * `state`). `transaction` is set when the op is part of an atomic batch.
+   */
+  writeCtx(kind, model, input, transaction) {
+    return transaction !== void 0 ? { kind, model, context: this.context, state: {}, input, transaction } : { kind, model, context: this.context, state: {}, input };
+  }
+  /**
+   * W1 — logical write, before effect derivation. Runs every `write.before` FIFO;
+   * a hook may mutate `ctx.input` / `ctx.kind` (incl. the delete→update rewrite)
+   * and may `throw` to cancel (in a transaction, the throw propagates and aborts
+   * the whole batch). The caller re-reads `ctx.kind` / `ctx.input` after this
+   * returns so a rewrite flows into derivation.
+   */
+  async runWriteBefore(ctx) {
+    for (const mw of this.chain) {
+      const before = mw.write?.before;
+      if (before) await before(ctx);
+    }
+  }
+  /**
+   * W2 — logical write, after commit. Runs every `write.after` LIFO with the
+   * committed change. Observe-only (no return threading); the SAME ctx W1
+   * produced is passed so a before/after pair shares `ctx.state`.
+   */
+  async runWriteAfter(ctx, change2) {
+    for (let i = this.chain.length - 1; i >= 0; i--) {
+      const after = this.chain[i].write?.after;
+      if (after) await after(ctx, change2);
+    }
+  }
+  /**
+   * W5 (logical-level) — runs every `write.onError` LIFO. A hook may **recover**
+   * by RETURNING a non-`undefined` value (the first such hook wins and
+   * 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, 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, err3);
+      if (recovered !== void 0) return recovered;
+    }
+    throw err3;
+  }
+  /** Build a W3/W4/W5 persist context (pure — no hooks run). */
+  persistCtx(items, origins, transaction) {
+    return transaction !== void 0 ? { items, origins, context: this.context, state: {}, transaction } : { items, origins, context: this.context, state: {} };
+  }
+  /**
+   * Drive the PHYSICAL persist of one composed batch through W3 → send → W4, with
+   * W5 (persist-level) on failure:
+   *
+   * 1. W3 (`write.persist.before`, FIFO) — may mutate `ctx.items`, may `throw`;
+   * 2. the caller's `send` runs against the (possibly mutated) `ctx.items`;
+   * 3. W4 (`write.persist.after`, LIFO) — observes the executor results;
+   * 4. on any throw, W5 (`write.persist.onError`, LIFO) runs: a hook may
+   *    **recover** by returning a value (treated as the send's result; W4 still
+   *    runs with it). If none recovers, the original error rethrows.
+   *
+   * The `send` closure receives the final `ctx.items` so a caller that sends what
+   * this method passes through observes a W3 mutation on the ACTUAL send. Returns
+   * the persist result (the executor's, or a W5-recovered value).
+   */
+  async runPersist(ctx, send) {
+    let results;
+    try {
+      for (const mw of this.chain) {
+        const before = mw.write?.persist?.before;
+        if (before) await before(ctx);
+      }
+      results = await send(ctx.items);
+    } 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, err3);
+        if (r !== void 0) {
+          recovered = r;
+          didRecover = true;
+          break;
+        }
+      }
+      if (!didRecover) throw err3;
+      results = recovered;
+    }
+    for (let i = this.chain.length - 1; i >= 0; i--) {
+      const after = this.chain[i].write?.persist?.after;
+      if (after) await after(ctx, results);
+    }
+    return results;
+  }
+};
+var NO_WRITE_MIDDLEWARE = new WriteRuntime([], {});
+
+// src/middleware/context.ts
+function buildReadRuntime(context) {
+  const chain = ClientManager.getMiddleware();
+  if (chain.length === 0) return NO_MIDDLEWARE;
+  return new MiddlewareRuntime(chain, context ?? {});
+}
+function buildWriteRuntime(context) {
+  const chain = ClientManager.getMiddleware();
+  if (chain.length === 0) return NO_WRITE_MIDDLEWARE;
+  return new WriteRuntime(chain, context ?? {});
+}
+var ctxModelCache = /* @__PURE__ */ new WeakMap();
+function ctxModelFor(modelClass) {
+  const cached2 = ctxModelCache.get(modelClass);
+  if (cached2) return cached2;
+  const asModel = modelClass.asModel;
+  if (typeof asModel !== "function") {
+    throw new Error(
+      "graphddb middleware: cannot resolve a ModelStatic for the read target (the model class has no static asModel()). This is an internal invariant."
+    );
+  }
+  const resolved = asModel.call(modelClass);
+  ctxModelCache.set(modelClass, resolved);
+  return resolved;
+}
+
+// src/operations/put.ts
 function buildPutInput(modelClass, item, options) {
   const meta = MetadataRegistry.get(modelClass);
   if (!meta.primaryKey) {
@@ -1714,12 +2586,21 @@ function buildPutInput(modelClass, item, options) {
   return putInput;
 }
 async function executePut(modelClass, item, options) {
+  const mw = writeRuntimeFor(options);
+  if (mw) {
+    await executeSingleWriteWithHooks({ kind: "put", modelClass, item, options }, mw);
+    return;
+  }
+  await executePutCore(modelClass, item, options);
+}
+async function executePutCore(modelClass, item, options, persistVia, forceOldImage) {
   const putInput = buildPutInput(modelClass, item, options);
-  const wantsOld = ChangeCaptureRegistry.wantsOldImage(modelClass);
-  const result = await ClientManager.getExecutor().put(putInput, {
+  const wantsOld = ChangeCaptureRegistry.wantsOldImage(modelClass) || forceOldImage === true;
+  const send = (input) => ClientManager.getExecutor().put(input, {
     ...wantsOld ? { returnOldImage: true } : {},
     ...options?.retry !== void 0 ? { retry: options.retry } : {}
   });
+  const result = persistVia ? await persistVia(putInput, send) : await send(putInput);
   if (ChangeCaptureRegistry.hasSubscribers()) {
     const oldItem = result.oldItem;
     captureWrite({
@@ -1733,95 +2614,163 @@ async function executePut(modelClass, item, options) {
   }
 }
 
-// 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.");
+// 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 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 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 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 { 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;
+    }
   }
-  const parts = [];
-  if (setClauses.length > 0) {
-    parts.push(`SET ${setClauses.join(", ")}`);
+  return deleteInput;
+}
+async function executeDelete(modelClass, keyObj, options) {
+  const mw = writeRuntimeFor(options);
+  if (mw) {
+    await executeSingleWriteWithHooks({ kind: "delete", modelClass, key: keyObj, options }, mw);
+    return;
   }
-  if (removeClauses.length > 0) {
-    parts.push(`REMOVE ${removeClauses.join(", ")}`);
+  await executeDeleteCore(modelClass, keyObj, options);
+}
+async function executeDeleteCore(modelClass, keyObj, options, persistVia, forceOldImage) {
+  const deleteInput = buildDeleteInput(modelClass, keyObj, options);
+  const wantsOld = ChangeCaptureRegistry.wantsOldImage(modelClass) || forceOldImage === true;
+  const send = (input) => ClientManager.getExecutor().delete(input, {
+    ...wantsOld ? { returnOldImage: true } : {},
+    ...options?.retry !== void 0 ? { retry: options.retry } : {}
+  });
+  const result = persistVia ? await persistVia(deleteInput, send) : await send(deleteInput);
+  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 } : {}
+    });
   }
-  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."
+// src/operations/write-hooks.ts
+function writeRuntimeFor(options) {
+  const mw = buildWriteRuntime(options?.context);
+  return mw.active ? mw : void 0;
+}
+async function executeSingleWriteWithHooks(req, mw) {
+  const input = {};
+  if (req.item !== void 0) input.item = { ...req.item };
+  if (req.key !== void 0) input.key = { ...req.key };
+  if (req.changes !== void 0) input.changes = { ...req.changes };
+  if (req.options !== void 0) input.options = { ...req.options };
+  const ctx = mw.writeCtx(req.kind, ctxModelFor(req.modelClass), input);
+  try {
+    await mw.runWriteBefore(ctx);
+    const change2 = await persistRewrittenWrite(req.modelClass, ctx, mw);
+    await mw.runWriteAfter(ctx, change2);
+  } catch (err3) {
+    await mw.runWriteError(ctx, err3);
+  }
+}
+async function persistRewrittenWrite(modelClass, ctx, mw) {
+  const opts = ctx.input.options;
+  const origin = { model: ctx.model, kind: ctx.kind };
+  const forceOldImage = mw.hasWriteAfter;
+  const cap = {};
+  if (ctx.kind === "put") {
+    await executePutCore(
+      modelClass,
+      ctx.input.item ?? {},
+      opts,
+      (input, send) => runPersist(mw, { Put: input }, origin, cap, (it) => {
+        const put = it.Put;
+        cap.newImage = put.Item;
+        return send(put);
+      }),
+      forceOldImage
+    );
+    return change(cap, true);
+  }
+  if (ctx.kind === "update") {
+    await executeUpdateCore(
+      modelClass,
+      ctx.input.key ?? {},
+      ctx.input.changes ?? {},
+      opts,
+      (input, send) => runPersist(mw, { Update: input }, origin, cap, (it) => {
+        const upd = it.Update;
+        const old = cap.result?.oldItem;
+        cap.newImage = { ...old ?? upd.Key, ...ctx.input.changes ?? {} };
+        return send(upd);
+      }),
+      forceOldImage
     );
+    return change(cap, true);
   }
-  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;
+  await executeDeleteCore(
+    modelClass,
+    ctx.input.key ?? {},
+    opts,
+    (input, send) => runPersist(
+      mw,
+      { Delete: input },
+      origin,
+      cap,
+      (it) => send(it.Delete)
+    ),
+    forceOldImage
+  );
+  return change(cap, false);
 }
-function readHiddenKey(entity) {
-  const value = entity[GRAPHDDB_KEY];
-  if (value === void 0) return void 0;
-  return value;
+function change(cap, withNew) {
+  const out = {};
+  const oldImage = cap.result?.oldItem;
+  if (oldImage !== void 0) out.oldImage = oldImage;
+  if (withNew && cap.newImage !== void 0) {
+    out.newImage = cap.newImage;
+  }
+  return out;
+}
+async function runPersist(mw, item, origin, cap, send) {
+  const ctx = mw.persistCtx([item], [origin]);
+  const result = await mw.runPersist(ctx, async (items) => send(items[0]));
+  cap.result = result;
+  return result;
 }
 
 // src/operations/update.ts
@@ -2035,6 +2984,17 @@ async function rederiveByReadModifyWrite(modelClass, entity, changes, options, p
   return buildUpdateInput(modelClass, enriched, changes, guarded);
 }
 async function executeUpdate(modelClass, entity, changes, options) {
+  const mw = writeRuntimeFor(options);
+  if (mw) {
+    await executeSingleWriteWithHooks(
+      { kind: "update", modelClass, key: entity, changes, options },
+      mw
+    );
+    return;
+  }
+  await executeUpdateCore(modelClass, entity, changes, options);
+}
+async function executeUpdateCore(modelClass, entity, changes, options, persistVia, forceOldImage) {
   let updateInput;
   if (options?.rederive === "read-modify-write") {
     const meta = MetadataRegistry.get(modelClass);
@@ -2066,11 +3026,12 @@ async function executeUpdate(modelClass, entity, changes, options) {
   } else {
     updateInput = buildUpdateInput(modelClass, entity, changes, options);
   }
-  const wantsOld = ChangeCaptureRegistry.wantsOldImage(modelClass);
-  const result = await ClientManager.getExecutor().update(updateInput, {
+  const wantsOld = ChangeCaptureRegistry.wantsOldImage(modelClass) || forceOldImage === true;
+  const send = (input) => ClientManager.getExecutor().update(input, {
     ...wantsOld ? { returnOldImage: true } : {},
     ...options?.retry !== void 0 ? { retry: options.retry } : {}
   });
+  const result = persistVia ? await persistVia(updateInput, send) : await send(updateInput);
   if (ChangeCaptureRegistry.hasSubscribers()) {
     const oldItem = result.oldItem;
     const keys = { pk: String(updateInput.Key.PK), sk: String(updateInput.Key.SK ?? "") };
@@ -2090,70 +3051,6 @@ async function executeUpdate(modelClass, entity, changes, options) {
   }
 }
 
-// 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 } : {},
-    ...options?.retry !== void 0 ? { retry: options.retry } : {}
-  });
-  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();
@@ -2216,12 +3113,21 @@ async function commitTransaction(items, options = {}) {
       `Transaction exceeds DynamoDB limit of ${MAX_TRANSACT_ITEMS} items`
     );
   }
-  await ClientManager.getExecutor().transactWrite(
-    collapsed,
+  const sendBatch = (items2) => ClientManager.getExecutor().transactWrite(
+    items2,
     options.retry !== void 0 ? { retry: options.retry } : void 0
   );
-  captureTransactItems(collapsed, options.modelBySignature ?? EMPTY_MODEL_MAP);
-  return collapsed;
+  let committed = collapsed;
+  if (options.middleware) {
+    const { runtime, origins, transaction } = options.middleware;
+    const persistCtx = runtime.persistCtx(collapsed, origins, transaction);
+    await runtime.runPersist(persistCtx, async (items2) => sendBatch(items2));
+    committed = persistCtx.items;
+  } else {
+    await sendBatch(collapsed);
+  }
+  captureTransactItems(committed, options.modelBySignature ?? EMPTY_MODEL_MAP);
+  return committed;
 }
 var EMPTY_MODEL_MAP = /* @__PURE__ */ new Map();
 function captureTransactItems(items, modelBySignature) {
@@ -2338,6 +3244,14 @@ function resolveModelClass(model) {
 var TransactionContext = class {
   items = [];
   captureMeta = [];
+  /**
+   * The logical write ops, parallel to {@link items} but EXCLUDING `conditionCheck`
+   * entries (those are read-only assertions, recorded only in `items`). Used by the
+   * write-hook path (#139) to run W1 on each logical op and recompose the batch.
+   * A `null` entry marks an `items` slot that has no logical op (a ConditionCheck),
+   * so the eager and logical arrays can be re-aligned at commit.
+   */
+  logicalOps = [];
   get itemCount() {
     return this.items.length;
   }
@@ -2346,6 +3260,7 @@ var TransactionContext = class {
     const modelClass = resolveModelClass(model);
     const putInput = buildPutInput(modelClass, item, options);
     this.items.push({ Put: putInput });
+    this.logicalOps.push({ kind: "put", modelClass, item, options });
     this.captureMeta.push({
       modelName: modelClass.name,
       op: "put",
@@ -2359,6 +3274,7 @@ var TransactionContext = class {
     const modelClass = resolveModelClass(model);
     const updateInput = buildUpdateInput(modelClass, entity, changes, options);
     this.items.push({ Update: updateInput });
+    this.logicalOps.push({ kind: "update", modelClass, key: entity, changes, options });
     this.captureMeta.push({
       modelName: modelClass.name,
       op: "update",
@@ -2371,6 +3287,7 @@ var TransactionContext = class {
     const modelClass = resolveModelClass(model);
     const deleteInput = buildDeleteInput(modelClass, key2, options);
     this.items.push({ Delete: deleteInput });
+    this.logicalOps.push({ kind: "delete", modelClass, key: key2, options });
     this.captureMeta.push({
       modelName: modelClass.name,
       op: "delete",
@@ -2412,11 +3329,16 @@ var TransactionContext = class {
       check.ExpressionAttributeValues = cond2.values;
     }
     this.items.push({ ConditionCheck: check });
+    this.logicalOps.push(null);
   }
   /** @internal */
   getTransactItems() {
     return this.items;
   }
+  /** @internal — the recorded logical write ops (issue #139 W1), `null` per ConditionCheck slot. */
+  getLogicalOps() {
+    return this.logicalOps;
+  }
   /** @internal — capture descriptors for the write-capture seam (issue #72). */
   getCaptureMeta() {
     return this.captureMeta;
@@ -2429,13 +3351,47 @@ var TransactionContext = class {
     }
   }
 };
-async function executeTransaction(fn) {
+async function executeTransaction(fn, options) {
   const tx = new TransactionContext();
   await fn(tx);
-  const transactItems = tx.getTransactItems();
+  let transactItems = tx.getTransactItems();
   if (transactItems.length === 0) {
     return;
   }
+  const writeMw = buildWriteRuntime(options?.context);
+  if (writeMw.active) {
+    const txId = { id: /* @__PURE__ */ Symbol("graphddb.transaction") };
+    const logical = tx.getLogicalOps();
+    const items = [...transactItems];
+    const origins = [];
+    const writeCtxs = [];
+    const modelBySignature2 = /* @__PURE__ */ new Map();
+    for (let i = 0; i < logical.length; i++) {
+      const op = logical[i];
+      if (op === null) continue;
+      const input = {};
+      if (op.item !== void 0) input.item = { ...op.item };
+      if (op.key !== void 0) input.key = { ...op.key };
+      if (op.changes !== void 0) input.changes = { ...op.changes };
+      if (op.options !== void 0) input.options = { ...op.options };
+      const ctx = writeMw.writeCtx(op.kind, ctxModelFor(op.modelClass), input, txId);
+      await writeMw.runWriteBefore(ctx);
+      const built = buildLogicalItem(op.modelClass, ctx);
+      items[i] = built;
+      modelBySignature2.set(execItemKeySignature(built), op.modelClass.name);
+      origins.push({ model: ctx.model, kind: ctx.kind });
+      writeCtxs.push(ctx);
+    }
+    transactItems = items;
+    await commitTransaction(transactItems, {
+      modelBySignature: modelBySignature2,
+      middleware: { runtime: writeMw, origins, transaction: txId }
+    });
+    for (let j = writeCtxs.length - 1; j >= 0; j--) {
+      await writeMw.runWriteAfter(writeCtxs[j], {});
+    }
+    return;
+  }
   const modelBySignature = /* @__PURE__ */ new Map();
   for (const meta of tx.getCaptureMeta()) {
     if (meta.modelName) {
@@ -2449,6 +3405,18 @@ async function executeTransaction(fn) {
     modelBySignature
   });
 }
+function buildLogicalItem(modelClass, ctx) {
+  const opts = ctx.input.options;
+  if (ctx.kind === "put") {
+    return { Put: buildPutInput(modelClass, ctx.input.item ?? {}, opts) };
+  }
+  if (ctx.kind === "update") {
+    return {
+      Update: buildUpdateInput(modelClass, ctx.input.key ?? {}, ctx.input.changes ?? {}, opts)
+    };
+  }
+  return { Delete: buildDeleteInput(modelClass, ctx.input.key ?? {}, opts) };
+}
 
 export {
   isColumn,
@@ -2475,6 +3443,7 @@ export {
   isParam,
   BATCH_GET_MAX_KEYS,
   BATCH_WRITE_MAX_ITEMS,
+  chunkArray,
   DynamoExecutor,
   DEFAULT_MAX_ATTEMPTS,
   DEFAULT_RETRY_POLICY,
@@ -2492,14 +3461,18 @@ export {
   serializeFieldValue,
   ChangeCaptureRegistry,
   captureWrite,
-  buildPutInput,
-  executePut,
+  NO_MIDDLEWARE,
+  buildReadRuntime,
+  buildWriteRuntime,
+  ctxModelFor,
   buildUpdateExpression,
   attachHiddenKey,
   buildUpdateInput,
   executeUpdate,
   buildDeleteInput,
   executeDelete,
+  buildPutInput,
+  executePut,
   MAX_TRANSACT_ITEMS,
   collapseSameKeyItems,
   commitTransaction,