graphddb 0.2.3 → 0.2.5

package/dist/{chunk-NJEC76TX.js → chunk-SGYBE2OV.js}

@@ -4,17 +4,22 @@ import {
   ClientManager,
   MAX_TRANSACT_ITEMS,
   MetadataRegistry,
+  NO_MIDDLEWARE,
   TableMapping,
   attachHiddenKey,
   attachModelClass,
   buildConditionExpression,
   buildDeleteInput,
   buildPutInput,
+  buildReadRuntime,
   buildUpdateInput,
+  buildWriteRuntime,
   captureWrite,
+  chunkArray,
   commitTransaction,
   compileRawCondition,
   createColumnMap,
+  ctxModelFor,
   execItemKeySignature,
   executeDelete,
   executePut,
@@ -32,7 +37,7 @@ import {
   serializeFieldValue,
   serializeRawCondition,
   skTemplate
-} from "./chunk-FWDJSGF3.js";
+} from "./chunk-4TYK3AV6.js";
 
 // src/spec/types.ts
 var SPEC_VERSION = "1.0";
@@ -686,8 +691,8 @@ function buildFromSegments(segmented, inputFieldNames, queryKey, pkAttr, skAttr)
 }
 
 // src/executor/executor.ts
-async function execute(operation) {
-  return ClientManager.getExecutor().execute(operation);
+async function execute(operation, options) {
+  return ClientManager.getExecutor().execute(operation, options);
 }
 
 // src/hydrator/hydrator.ts
@@ -810,20 +815,71 @@ async function executeListInternal(modelClass, key, selectSpec, options = {}) {
     updatable: options.updatable ?? false
   });
   const operation = executionPlan.operations[0];
-  const result = await execute(operation);
-  const rawItems = result.items;
+  const mw = options.mw ?? NO_MIDDLEWARE;
+  const sendList = (op) => execute(op, options.retry !== void 0 ? { retry: options.retry } : void 0).then(
+    (r) => r
+  );
+  let lastEvaluatedKey;
+  let rawItems;
+  if (mw.active) {
+    let captured;
+    const opModel = ctxModelFor(modelClass);
+    rawItems = await mw.runOp(
+      operation,
+      options.relationPath ?? [],
+      opModel,
+      async (op) => {
+        captured = await sendList(op);
+        return captured.items;
+      }
+    );
+    lastEvaluatedKey = captured?.lastEvaluatedKey;
+  } else {
+    const result = await sendList(operation);
+    rawItems = result.items;
+    lastEvaluatedKey = result.lastEvaluatedKey;
+  }
   const hydrated = hydrate(rawItems, select, metadata, options.updatable ?? false);
-  const cursor = result.lastEvaluatedKey ? encodeCursor(result.lastEvaluatedKey) : null;
+  const cursor = lastEvaluatedKey ? encodeCursor(lastEvaluatedKey) : null;
   return { items: hydrated, rawItems, cursor };
 }
 async function executeList(modelClass, key, selectSpec, options = {}) {
-  const { items, cursor } = await executeListInternal(
-    modelClass,
-    key,
-    selectSpec,
-    options
-  );
-  return { items, cursor };
+  const mw = buildReadRuntime(options.context);
+  if (!mw.active) {
+    const { items, cursor } = await executeListInternal(
+      modelClass,
+      key,
+      selectSpec,
+      options
+    );
+    return { items, cursor };
+  }
+  const ctxModel = ctxModelFor(modelClass);
+  const opts = { ...options };
+  const params = {
+    key: { ...key },
+    select: selectSpec && typeof selectSpec === "object" ? selectSpec : {},
+    options: opts
+  };
+  let reqCtx;
+  try {
+    reqCtx = await mw.runRequestBefore("list", ctxModel, params);
+    const { items, cursor } = await executeListInternal(
+      modelClass,
+      params.key,
+      params.select,
+      // Thread the SAME runtime + an empty (root) relation path so R2/R3 fire on
+      // the partition Query; carry the (possibly R1-mutated) per-call options.
+      { ...params.options, mw, relationPath: [] }
+    );
+    const result = { items, cursor };
+    return await mw.runRequestAfter(reqCtx, result);
+  } catch (err) {
+    return mw.runRequestError(
+      reqCtx ?? mw.requestCtx("list", ctxModel, params),
+      err
+    );
+  }
 }
 
 // src/planner/relation-planner.ts
@@ -1171,9 +1227,23 @@ async function fetchBelongsToHasOneBatch(rel, rawParentItems, selectSpec, target
   );
   const executor = ClientManager.getExecutor();
   const queryKeyToRaw = /* @__PURE__ */ new Map();
+  const mw = options.mw ?? NO_MIDDLEWARE;
+  const opPath = [...options.relationPath ?? [], rel.propertyName];
+  const opModel = mw.active ? ctxModelFor(rel.targetFactory()) : void 0;
   for (const operation of batchOps) {
-    const batchResult = await executor.batchGet(operation);
-    for (const item of batchResult.items) {
+    const items = mw.active ? await mw.runOp(
+      operation,
+      opPath,
+      opModel,
+      (op) => executor.batchGet(
+        op,
+        options.retry !== void 0 ? { retry: options.retry } : void 0
+      ).then((r) => r.items)
+    ) : (await executor.batchGet(
+      operation,
+      options.retry !== void 0 ? { retry: options.retry } : void 0
+    )).items;
+    for (const item of items) {
       for (const queryKey of queryKeys) {
         if (!matchesQueryKey(item, queryKey)) {
           continue;
@@ -1259,9 +1329,11 @@ async function resolveRelations(parentItem, rawParentItem, select, metadata, opt
   const relations = detectRelationFields(select, metadata);
   const plan2 = options.plan ?? (currentPath === "$" ? buildRelationExecutionPlan(select, metadata) : void 0);
   const opts = plan2 === options.plan ? options : { ...options, plan: plan2 };
+  const basePath = opts.relationPath ?? [];
   await runStaged(relations, currentPath, opts.plan, async (rel) => {
     const selectSpec = relationSpec(select[rel.propertyName]);
     const ownPath = relationResultPath(currentPath, rel);
+    const relPath = [...basePath, rel.propertyName];
     if (rel.type === "hasMany") {
       const targetClass2 = rel.targetFactory();
       const queryKey = buildRelationQueryKey(rel, rawParentItem);
@@ -1272,7 +1344,10 @@ async function resolveRelations(parentItem, rawParentItem, select, metadata, opt
         after: selectSpec.after,
         order,
         filter: selectSpec.filter,
-        updatable: opts.updatable
+        updatable: opts.updatable,
+        retry: opts.retry,
+        mw: opts.mw,
+        relationPath: relPath
       });
       let items = listResult.items;
       const rawItems = listResult.rawItems;
@@ -1284,7 +1359,7 @@ async function resolveRelations(parentItem, rawParentItem, select, metadata, opt
           rawItems,
           selectSpec.select,
           targetMeta2,
-          opts,
+          { ...opts, relationPath: relPath },
           currentDepth + 1,
           ownPath
         );
@@ -1313,6 +1388,36 @@ async function resolveRelations(parentItem, rawParentItem, select, metadata, opt
 
 // src/operations/query.ts
 async function executeQuery(modelClass, key, selectSpec, options) {
+  const mw = buildReadRuntime(options?.context);
+  if (!mw.active) {
+    return executeQueryInner(modelClass, key, selectSpec, options, mw);
+  }
+  const ctxModel = ctxModelFor(modelClass);
+  const opts = { ...options ?? {} };
+  const params = {
+    key: { ...key },
+    select: selectSpec && typeof selectSpec === "object" ? selectSpec : {},
+    options: opts
+  };
+  let reqCtx;
+  try {
+    reqCtx = await mw.runRequestBefore("query", ctxModel, params);
+    const result = await executeQueryInner(
+      modelClass,
+      params.key,
+      params.select,
+      params.options,
+      mw
+    );
+    return await mw.runRequestAfter(reqCtx, result);
+  } catch (err) {
+    return mw.runRequestError(
+      reqCtx ?? mw.requestCtx("query", ctxModel, params),
+      err
+    );
+  }
+}
+async function executeQueryInner(modelClass, key, selectSpec, options, mw) {
   const metadata = MetadataRegistry.get(modelClass);
   const queryFields = Object.keys(key);
   const resolved = resolveKey(queryFields, metadata);
@@ -1345,8 +1450,26 @@ async function executeQuery(modelClass, key, selectSpec, options) {
       (sourceField) => key[sourceField] != null
     )
   );
-  const parentPromise = execute(operation);
-  const relationPromise = canParallelizeRelations ? resolveRelations({}, key, select, metadata, { maxDepth, updatable }, 1) : null;
+  const retry = options?.retry;
+  const sendRoot = () => execute(operation, retry !== void 0 ? { retry } : void 0);
+  const parentPromise = mw.active ? (() => {
+    const opModel = ctxModelFor(modelClass);
+    return mw.runOp(operation, [], opModel, async (op) => {
+      const r = await execute(
+        op,
+        retry !== void 0 ? { retry } : void 0
+      );
+      return r.items;
+    }).then((items) => ({ items }));
+  })() : sendRoot();
+  const relationPromise = canParallelizeRelations ? resolveRelations(
+    {},
+    key,
+    select,
+    metadata,
+    { maxDepth, updatable, retry, mw, relationPath: [] },
+    1
+  ) : null;
   let result;
   try {
     result = await parentPromise;
@@ -1373,7 +1496,7 @@ async function executeQuery(modelClass, key, selectSpec, options) {
         rawItem,
         select,
         metadata,
-        { maxDepth, updatable },
+        { maxDepth, updatable, retry, mw, relationPath: [] },
         1
       );
       if (hydratedItem && updatable) {
@@ -1454,16 +1577,37 @@ function hydrateBatchItems(rawItems, metadata) {
     return merged;
   });
 }
-async function executeBatchGetForTable(tableName, entries) {
+async function executeBatchGetForTable(tableName, entries, mw, opModel) {
   const groups = /* @__PURE__ */ new Map();
   if (entries.length === 0) {
     return groups;
   }
   const keys = entries.map((entry) => entry.dynamoKey);
-  const { items: rawItems } = await ClientManager.getExecutor().batchGet({
-    tableName,
-    keys
-  });
+  const sendChunk = (op) => execute(op).then((r) => r.items);
+  let rawItems;
+  if (mw.active) {
+    rawItems = [];
+    for (const chunk of chunkArray(keys, BATCH_GET_MAX_KEYS)) {
+      const operation = {
+        type: "BatchGetItem",
+        tableName,
+        keys: chunk
+      };
+      const chunkItems = await mw.runOp(
+        operation,
+        [],
+        opModel,
+        (op) => sendChunk(op)
+      );
+      rawItems.push(...chunkItems);
+    }
+  } else {
+    const { items } = await ClientManager.getExecutor().batchGet({
+      tableName,
+      keys
+    });
+    rawItems = items;
+  }
   const entriesByModel = /* @__PURE__ */ new Map();
   for (const entry of entries) {
     const existing = entriesByModel.get(entry.modelClass) ?? [];
@@ -1484,12 +1628,42 @@ async function executeBatchGetForTable(tableName, entries) {
   }
   return groups;
 }
-async function executeBatchGet(requests) {
+async function executeBatchGet(requests, options) {
+  const mw = buildReadRuntime(options?.context);
+  if (!mw.active || requests.length === 0) {
+    return executeBatchGetInner(requests, mw);
+  }
+  const firstModel = ctxModelFor(resolveModelClass(requests[0].model));
+  const reqList = [...requests];
+  const params = {
+    key: {},
+    select: {},
+    options: {},
+    requests: reqList
+  };
+  let reqCtx;
+  try {
+    reqCtx = await mw.runRequestBefore("batchGet", firstModel, params);
+    const effectiveRequests = params.requests;
+    const result = await executeBatchGetInner(effectiveRequests, mw);
+    return await mw.runRequestAfter(reqCtx, result);
+  } catch (err) {
+    return mw.runRequestError(
+      reqCtx ?? mw.requestCtx("batchGet", firstModel, params),
+      err
+    );
+  }
+}
+async function executeBatchGetInner(requests, mw) {
   const entriesByTable = /* @__PURE__ */ new Map();
+  const firstModelClassByTable = /* @__PURE__ */ new Map();
   for (const request of requests) {
     const modelClass = resolveModelClass(request.model);
     const metadata = MetadataRegistry.get(modelClass);
     const tableName = TableMapping.resolve(metadata.tableName);
+    if (!firstModelClassByTable.has(tableName)) {
+      firstModelClassByTable.set(tableName, modelClass);
+    }
     for (const keyObj of request.keys) {
       const entry = {
         modelClass,
@@ -1504,7 +1678,13 @@ async function executeBatchGet(requests) {
   const mergedGroups = /* @__PURE__ */ new Map();
   for (const [, entries] of entriesByTable) {
     const tableName = TableMapping.resolve(entries[0].metadata.tableName);
-    const tableGroups = await executeBatchGetForTable(tableName, entries);
+    const opModel = mw.active ? ctxModelFor(firstModelClassByTable.get(tableName) ?? entries[0].modelClass) : void 0;
+    const tableGroups = await executeBatchGetForTable(
+      tableName,
+      entries,
+      mw,
+      opModel
+    );
     for (const [modelClass, items] of tableGroups) {
       const existing = mergedGroups.get(modelClass) ?? [];
       mergedGroups.set(modelClass, existing.concat(items));
@@ -1894,8 +2074,11 @@ function renderWrite(op, key, params, contextLabel) {
   }
   return base;
 }
-async function executeSingleWrite(w) {
-  const options = w.condition !== void 0 ? { condition: w.condition } : void 0;
+async function executeSingleWrite(w, retry) {
+  const options = w.condition !== void 0 || retry !== void 0 ? {
+    ...w.condition !== void 0 ? { condition: w.condition } : {},
+    ...retry !== void 0 ? { retry } : {}
+  } : void 0;
   if (w.operation === "put") {
     await executePut(w.modelClass, w.item ?? {}, options);
     return;
@@ -2062,7 +2245,7 @@ function renderIdempotencyGuardItems(guard, key, params, contextLabel) {
     return { Put: put };
   });
 }
-async function executeReferentialTransaction(writes, edgeItems, updateItems, guardItemsRaw, outboxItems, idempotencyItems, checks, methodName, modelBySignature = /* @__PURE__ */ new Map()) {
+async function executeReferentialTransaction(writes, edgeItems, updateItems, guardItemsRaw, outboxItems, idempotencyItems, checks, methodName, modelBySignature = /* @__PURE__ */ new Map(), retry, middleware) {
   const writeItems = writes.map((w) => {
     const options = w.condition !== void 0 ? { condition: w.condition } : void 0;
     let item;
@@ -2089,6 +2272,8 @@ async function executeReferentialTransaction(writes, edgeItems, updateItems, gua
     ],
     {
       modelBySignature,
+      ...retry !== void 0 ? { retry } : {},
+      ...middleware !== void 0 ? { middleware } : {},
       limitError: (count) => new Error(
         `Contract runtime: command method '${methodName}' composes ${count} items (writes + edges + derived updates + uniqueness guards + outbox events + idempotency guard + ConditionChecks) into one TransactWriteItems, but DynamoDB caps a transaction at ${MAX_TRANSACT_ITEMS} items and a transaction is atomic \u2014 it cannot be split. Reduce the fragment / effect count.`
       )
@@ -2302,7 +2487,24 @@ function readBackForCompiledOp(op, write) {
 }
 async function executeCompiledWriteOp(ops, options) {
   const label = options.label;
-  const renderedOps = ops.map((op, i) => renderCompiledOp(op, `${label} (op #${i})`));
+  const writeMw = buildWriteRuntime(options.context);
+  const writeCtxs = [];
+  const txId = { id: /* @__PURE__ */ Symbol("graphddb.mutate") };
+  let rewrites = [];
+  if (writeMw.active) {
+    const w1ed = [];
+    for (const op of ops) {
+      const r = await runEnvelopeW1(op, writeMw, txId, writeCtxs);
+      w1ed.push(r.op);
+      rewrites.push(r.rewritten ?? null);
+    }
+    ops = w1ed;
+  } else {
+    rewrites = ops.map(() => null);
+  }
+  const renderedOps = ops.map(
+    (op, i) => rewrites[i] !== null ? rewrittenCompiledOp(rewrites[i]) : renderCompiledOp(op, `${label} (op #${i})`)
+  );
   const rendered = renderedOps.map((r) => r.write);
   const modelBySignature = /* @__PURE__ */ new Map();
   const edgeItems = [];
@@ -2321,8 +2523,13 @@ async function executeCompiledWriteOp(ops, options) {
     checkItems.push(...r.checkItems);
   }
   const hasDerivedEffects = renderedOps.some((r) => r.hasDerivedEffects);
+  const origins = writeMw.active ? rendered.map((w) => ({ model: ctxModelFor(w.modelClass), kind: w.operation })) : [];
   if (rendered.length === 1 && !hasDerivedEffects) {
-    await executeSingleWrite(rendered[0]);
+    if (writeMw.active) {
+      await persistSingleWriteWithHooks(rendered[0], writeMw, origins, txId, options.retry);
+    } else {
+      await executeSingleWrite(rendered[0], options.retry);
+    }
   } else {
     await executeReferentialTransaction(
       rendered,
@@ -2333,23 +2540,116 @@ async function executeCompiledWriteOp(ops, options) {
       idempotencyItems,
       checkItems,
       label,
-      modelBySignature
+      modelBySignature,
+      options.retry,
+      writeMw.active ? { runtime: writeMw, origins, transaction: txId } : void 0
     );
   }
+  if (writeMw.active) {
+    for (let i = writeCtxs.length - 1; i >= 0; i--) {
+      await writeMw.runWriteAfter(writeCtxs[i], {});
+    }
+  }
   const readBacks = await Promise.all(
     ops.map((op, i) => readBackForCompiledOp(op, rendered[i]))
   );
   return { readBacks };
 }
+async function persistSingleWriteWithHooks(w, runtime, origins, transaction, retry) {
+  const options = w.condition !== void 0 || retry !== void 0 ? {
+    ...w.condition !== void 0 ? { condition: w.condition } : {},
+    ...retry !== void 0 ? { retry } : {}
+  } : void 0;
+  let item;
+  if (w.operation === "put") {
+    item = { Put: buildPutInput(w.modelClass, w.item ?? {}, options) };
+  } else if (w.operation === "update") {
+    item = { Update: buildUpdateInput(w.modelClass, w.key, w.changes ?? {}, options) };
+  } else {
+    item = { Delete: buildDeleteInput(w.modelClass, w.key, options) };
+  }
+  const persistCtx = runtime.persistCtx([item], origins, transaction);
+  await runtime.runPersist(persistCtx, async (items) => {
+    const sent = items[0];
+    const sendOpts = retry !== void 0 ? { retry } : void 0;
+    const exec = ClientManager.getExecutor();
+    if ("Put" in sent) return exec.put(sent.Put, sendOpts);
+    if ("Update" in sent) return exec.update(sent.Update, sendOpts);
+    if ("Delete" in sent) return exec.delete(sent.Delete, sendOpts);
+    throw new Error("graphddb middleware: a single-op persist received a ConditionCheck.");
+  });
+}
+async function runEnvelopeW1(op, runtime, transaction, writeCtxs) {
+  const kind = op.fragment.op.operation;
+  const keyFields = new Set(op.fragment.keyFields);
+  const input = {};
+  if (kind === "put") {
+    input.item = { ...op.params };
+  } else {
+    const key = {};
+    const changes = {};
+    for (const [k, v] of Object.entries(op.params)) {
+      if (keyFields.has(k)) key[k] = v;
+      else changes[k] = v;
+    }
+    input.key = key;
+    input.changes = changes;
+  }
+  const modelClass = op.fragment.op.entity.modelClass;
+  const ctx = runtime.writeCtx(kind, ctxModelFor(modelClass), input, transaction);
+  await runtime.runWriteBefore(ctx);
+  writeCtxs.push(ctx);
+  if (ctx.kind !== kind) {
+    return { op, rewritten: renderRewrittenWrite(modelClass, ctx) };
+  }
+  const merged = ctx.kind === "put" ? { ...ctx.input.item ?? {} } : { ...ctx.input.key ?? {}, ...ctx.input.changes ?? {} };
+  return { op: { ...op, params: merged } };
+}
+function renderRewrittenWrite(modelClass, ctx) {
+  const modelStatic = modelClass.asModel();
+  const condition = ctx.input.options?.condition;
+  const base = {
+    modelClass,
+    modelStatic,
+    ...condition !== void 0 ? { condition } : {}
+  };
+  if (ctx.kind === "put") {
+    const item = ctx.input.item ?? {};
+    return { ...base, operation: "put", key: item, item };
+  }
+  if (ctx.kind === "update") {
+    return {
+      ...base,
+      operation: "update",
+      key: ctx.input.key ?? {},
+      changes: ctx.input.changes ?? {}
+    };
+  }
+  return { ...base, operation: "delete", key: ctx.input.key ?? {} };
+}
+function rewrittenCompiledOp(write) {
+  return {
+    write,
+    edgeItems: [],
+    updateItems: [],
+    guardItems: [],
+    outboxItems: [],
+    idempotencyItems: [],
+    checkItems: [],
+    modelBySignature: /* @__PURE__ */ new Map(),
+    hasDerivedEffects: false
+  };
+}
 async function executeCompiledParallelWrites(ops, options) {
   const label = options.label;
   const results = new Array(ops.length);
   const renderedOps = ops.map((op, i) => renderCompiledOp(op, `${label} (op #${i})`));
   const coalescibleIdx = [];
   const individualIdx = [];
+  const hooksActive = buildWriteRuntime(options.context).active;
   renderedOps.forEach((r, i) => {
     const w = r.write;
-    if (!r.hasDerivedEffects && w.condition === void 0 && (w.operation === "put" || w.operation === "delete")) {
+    if (!hooksActive && !r.hasDerivedEffects && w.condition === void 0 && (w.operation === "put" || w.operation === "delete")) {
       coalescibleIdx.push(i);
     } else {
       individualIdx.push(i);
@@ -2380,7 +2680,9 @@ async function executeCompiledParallelWrites(ops, options) {
     ...individualIdx.map(async (i) => {
       try {
         const { readBacks } = await executeCompiledWriteOp([ops[i]], {
-          label: `${label} (op #${i})`
+          label: `${label} (op #${i})`,
+          ...options.retry !== void 0 ? { retry: options.retry } : {},
+          ...options.context !== void 0 ? { context: options.context } : {}
         });
         results[i] = { ok: true, value: readBacks[0] };
       } catch (e) {
@@ -2438,14 +2740,16 @@ async function executeReadRoute(alias, route) {
   if (isQuery) {
     return executeQuery(modelClass, route.key, route.select, {
       consistentRead: opt.consistentRead,
-      maxDepth: opt.maxDepth
+      maxDepth: opt.maxDepth,
+      context: opt.context
     });
   }
   return executeList(modelClass, route.key, route.select, {
     limit: opt.limit,
     after: opt.after,
     order: opt.order,
-    filter: opt.filter
+    filter: opt.filter,
+    context: opt.context
   });
 }
 var INTENT_KEYS = ["create", "update", "remove"];
@@ -2459,9 +2763,9 @@ async function executeWriteEnvelope(envelope, options = {}) {
   }
   const ops = aliases.flatMap((alias) => normalizeWriteOp(alias, envelope[alias]));
   if (mode === "transaction") {
-    return executeTransactionMode(ops);
+    return executeTransactionMode(ops, options.retry, options.context);
   }
-  return executeParallelMode(ops);
+  return executeParallelMode(ops, options.retry, options.context);
 }
 function normalizeWriteOp(alias, d) {
   if (d === null || typeof d !== "object") {
@@ -2534,10 +2838,12 @@ function mapToRefs($, fields) {
   for (const f of fields) out[f] = $[f];
   return out;
 }
-async function executeTransactionMode(ops) {
+async function executeTransactionMode(ops, retry, context) {
   const compiled = ops.map(compileWriteOp);
   const { readBacks } = await executeCompiledWriteOp(compiled, {
-    label: "DDBModel.mutate"
+    label: "DDBModel.mutate",
+    ...retry !== void 0 ? { retry } : {},
+    ...context !== void 0 ? { context } : {}
   });
   const out = {};
   ops.forEach((op, i) => {
@@ -2552,10 +2858,12 @@ async function executeTransactionMode(ops) {
   });
   return out;
 }
-async function executeParallelMode(ops) {
+async function executeParallelMode(ops, retry, context) {
   const compiled = ops.map(compileWriteOp);
   const settled = await executeCompiledParallelWrites(compiled, {
-    label: "DDBModel.mutate"
+    label: "DDBModel.mutate",
+    ...retry !== void 0 ? { retry } : {},
+    ...context !== void 0 ? { context } : {}
   });
   const out = {};
   ops.forEach((op, i) => {
@@ -2587,14 +2895,64 @@ function resolveModelStatic(ref, alias) {
 
 // src/model/DDBModel.ts
 var DDBModel = class {
+  /**
+   * Register the `DynamoDBClient` GraphDDB sends through.
+   *
+   * IMPORTANT (issue #111): GraphDDB now owns single-op throttle / transient-error
+   * retry (see {@link setRetryPolicy}), so a client left at the AWS SDK default
+   * `maxAttempts: 3` retries MULTIPLICATIVELY underneath the library. Construct the
+   * client with `maxAttempts: 1` so the library is the single source of truth for
+   * retry — e.g. `new DynamoDBClient({ maxAttempts: 1 })`. GraphDDB does NOT mutate
+   * a client you pass in.
+   */
   static setClient(client) {
     ClientManager.setClient(client);
   }
   static setTableMapping(mapping) {
     TableMapping.set(mapping);
   }
-  static async transaction(fn) {
-    await executeTransaction(fn);
+  /**
+   * Configure the global single-op retry policy (issue #111) — exponential backoff
+   * + jitter with a bounded attempt cap, applied to every GetItem / Query / Put /
+   * Update / Delete / relation-fan-out send and to `TransactWriteItems`. Mirrors
+   * {@link setClient} / {@link setTableMapping}. A sensible default is ALWAYS on; call
+   * this only to tune it (or pass `null` to restore the default). A per-call
+   * `retry?: RetryPolicy | false` on an operation's options overrides this globally
+   * for that call (`false` disables retry).
+   */
+  static setRetryPolicy(policy) {
+    ClientManager.setRetryPolicy(policy);
+  }
+  /**
+   * Register a {@link Middleware} (issue #50; read path #138, write path #139).
+   * One registered object may carry read and/or write hooks.
+   *
+   * - **Read** R1–R5 — request entry (`read.before`), each physical op before send
+   *   / after raw fetch (`read.op.before` / `read.op.afterFetch`, INCLUDING every
+   *   relation fan-out fetch), the final hydrated result (`read.afterFetch`), and on
+   *   error (`read.op.onError` / `read.onError`).
+   * - **Write** W1–W5 — the logical write before effect derivation (`write.before`,
+   *   may mutate `ctx.input` / `ctx.kind` incl. a delete→update rewrite), after commit
+   *   (`write.after`), the physical persist on the fully composed batch
+   *   (`write.persist.before` / `write.persist.after`, fires ONCE per atomic
+   *   transaction), and on error (`write.persist.onError` / `write.onError`).
+   *
+   * Hooks may observe, mutate `ctx`, `throw` to cancel, or (on `onError`) recover by
+   * returning a value; the library imposes no semantics. Ordering: `before*` runs
+   * first-registered-first (FIFO); `after*` / `onError` run last-registered-first
+   * (LIFO). Mirrors {@link setRetryPolicy} — a host-runtime global stored on
+   * {@link ClientManager}; never serialized (the bridge #48 is unaffected). Per-call
+   * host context flows in via the read's / write's `{ context }` option.
+   */
+  static use(mw) {
+    ClientManager.use(mw);
+  }
+  /** Remove every registered middleware (read AND write; teardown / tests). See {@link use}. */
+  static clearMiddleware() {
+    ClientManager.clearMiddleware();
+  }
+  static async transaction(fn, options) {
+    await executeTransaction(fn, options);
   }
   /**
    * In-process multi-route READ (issue #101 — the unified envelope). Each alias
@@ -2609,8 +2967,20 @@ var DDBModel = class {
   static mutate(envelope, options) {
     return executeWriteEnvelope(envelope, options);
   }
-  static async batchGet(requests) {
-    return executeBatchGet(requests);
+  /**
+   * Multi-key, multi-model batch read. Each {@link BatchGetRequest} contributes its
+   * keys to a chunked `BatchGetItem` per physical table; results are re-grouped by
+   * model on the returned {@link BatchGetResult}.
+   *
+   * Fires the read hooks (issue #142): request-level R1/R4/R5 with kind
+   * `'batchGet'`, and op-level R2/R3/R5 for each underlying physical `BatchGetItem`
+   * op. The optional `{ context }` is exposed to every hook as `ctx.context` and
+   * threaded UNCHANGED to every op (absent ⇒ `{}`), so a global hook (e.g. a
+   * tenant-scope R2 FilterExpression) applies across the whole batch. With no
+   * middleware registered the read path is unchanged (zero-overhead fast path).
+   */
+  static async batchGet(requests, options) {
+    return executeBatchGet(requests, options);
   }
   static async batchWrite(requests) {
     return executeBatchWrite(requests);