graphddb 0.2.4 → 0.2.5

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

@@ -834,6 +834,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 +874,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 +949,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 +1492,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 +1694,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,6 +1791,278 @@ function captureWrite(record) {
   ChangeCaptureRegistry.emit(record);
 }
 
+// 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, err) {
+    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);
+      if (recovered !== void 0) return recovered;
+    }
+    throw err;
+  }
+  /**
+   * 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 (err) {
+      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);
+        if (recovered !== void 0) return recovered;
+      }
+      throw err;
+    }
+  }
+};
+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, err) {
+    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);
+      if (recovered !== void 0) return recovered;
+    }
+    throw err;
+  }
+  /** 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 (err) {
+      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);
+        if (r !== void 0) {
+          recovered = r;
+          didRecover = true;
+          break;
+        }
+      }
+      if (!didRecover) throw err;
+      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);
@@ -1714,12 +2129,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 +2157,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 (err) {
+    await mw.runWriteError(ctx, err);
+  }
+}
+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 +2527,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 +2569,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 +2594,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 +2656,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 +2787,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 +2803,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 +2817,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 +2830,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 +2872,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 +2894,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 +2948,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 +2986,7 @@ export {
   isParam,
   BATCH_GET_MAX_KEYS,
   BATCH_WRITE_MAX_ITEMS,
+  chunkArray,
   DynamoExecutor,
   DEFAULT_MAX_ATTEMPTS,
   DEFAULT_RETRY_POLICY,
@@ -2492,14 +3004,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,