graphddb 0.2.2 → 0.2.4

package/README.md

@@ -77,8 +77,10 @@ class UserModel extends DDBModel {
 }
 const User = UserModel.asModel();
 
-// Wire up the DynamoDB client once (configure retries/region on the client itself).
-DDBModel.setClient(new DynamoDBClient({}));
+// Wire up the DynamoDB client once. GraphDDB owns throttle/transient retry
+// (see "Retry & throttling" below), so set the client to `maxAttempts: 1` to
+// avoid retrying twice (SDK × library).
+DDBModel.setClient(new DynamoDBClient({ maxAttempts: 1 }));
 
 // Read — only the selected fields appear in the result type.
 const user = await User.query({ userId: 'alice' }, { name: true });
@@ -95,6 +97,50 @@ await DDBModel.mutate({
 For cross-service contracts, the Python bridge, multi-fragment atomic mutations,
 and more, see the sections below and [`docs/spec.md`](./docs/spec.md).
 
+## Retry & throttling
+
+GraphDDB retries throttle / transient errors on **every** single-item op
+(`GetItem` / `Query` / `PutItem` / `UpdateItem` / `DeleteItem`), the relation
+read fan-out, and `TransactWriteItems` — out of the box, with no configuration.
+The default policy is exponential backoff (`min(1000, 50·2^(n-1))` ms) with full
+jitter, capped at 10 attempts, retrying only throttle / 5xx / transient errors
+(never `ValidationException` or a conditional-check failure). A cancelled
+transaction is inspected per-reason: a `ConditionalCheckFailed` reason throws
+immediately, a purely throttle-induced cancellation is retried.
+
+> This is the library's own **error retry**, distinct from the partial-batch
+> `UnprocessedKeys` / `UnprocessedItems` retry that `batchGet` / `batchWrite`
+> already perform. Both use the same backoff ramp but are separate mechanisms.
+
+**Set your client to `maxAttempts: 1`.** Now that the library owns retry, leaving
+the AWS SDK at its default (`maxAttempts: 3`) retries *multiplicatively*
+underneath GraphDDB. Make the library the single source of truth:
+
+```ts
+DDBModel.setClient(new DynamoDBClient({ maxAttempts: 1 }));
+```
+
+GraphDDB never mutates a client you pass in — this is on you to set.
+
+Tune the policy globally, or per call:
+
+```ts
+import { DDBModel } from 'graphddb';
+
+// Global override (mirrors setClient / setTableMapping). `null` restores the default.
+DDBModel.setRetryPolicy({
+  maxAttempts: 5,
+  jitter: 'full', // or 'none'
+  onRetry: ({ attempt, error, delayMs, operation }) => {
+    console.warn(`retry #${attempt} of ${operation} after ${delayMs}ms`, error);
+  },
+});
+
+// Per-call override on any op's options (`RetryPolicy | false`). `false` disables retry.
+await User.putItem({ userId: 'alice', name: 'Alice' }, { retry: false });
+await User.query({ userId: 'alice' }, { name: true }, { retry: { maxAttempts: 3 } });
+```
+
 ## User Permissions Example
 
 The [user-permissions](./examples/user-permissions/) example models users, groups, memberships, and permissions in a single DynamoDB table.

package/dist/{chunk-3MI43FHU.js → chunk-GCPEUPAA.js}

@@ -651,6 +651,189 @@ async function batchWriteChunkWithRetry(docClient, tableName, entries, toCommand
   }
 }
 
+// src/executor/retry-policy.ts
+var DEFAULT_MAX_ATTEMPTS = 10;
+var DEFAULT_RETRY_POLICY = {
+  maxAttempts: DEFAULT_MAX_ATTEMPTS,
+  computeDelay: computeBackoffDelay,
+  jitter: "full",
+  isRetryable: isRetryableError
+};
+var THROTTLE_ERROR_NAMES = /* @__PURE__ */ new Set([
+  "ProvisionedThroughputExceededException",
+  "ThrottlingException",
+  "ThrottlingError",
+  "RequestLimitExceeded",
+  "RequestThrottled",
+  "RequestThrottledException",
+  "TooManyRequestsException"
+]);
+var TRANSIENT_ERROR_NAMES = /* @__PURE__ */ new Set([
+  "InternalServerError",
+  "InternalServerErrorException",
+  "InternalFailure",
+  "ServiceUnavailable",
+  "ServiceUnavailableException"
+]);
+var NON_RETRYABLE_ERROR_NAMES = /* @__PURE__ */ new Set([
+  "ValidationException",
+  "ConditionalCheckFailedException",
+  "ResourceNotFoundException",
+  "AccessDeniedException",
+  "ResourceInUseException",
+  "ItemCollectionSizeLimitExceededException"
+]);
+function errorName(error) {
+  if (typeof error !== "object" || error === null) return void 0;
+  const e = error;
+  if (typeof e.name === "string") return e.name;
+  if (typeof e.__type === "string") {
+    const t = e.__type;
+    const hash = t.lastIndexOf("#");
+    return hash >= 0 ? t.slice(hash + 1) : t;
+  }
+  return void 0;
+}
+function httpStatusCode(error) {
+  if (typeof error !== "object" || error === null) return void 0;
+  const meta = error.$metadata;
+  const code = meta?.httpStatusCode;
+  return typeof code === "number" ? code : void 0;
+}
+function isRetryableError(error) {
+  const name = errorName(error);
+  if (name && NON_RETRYABLE_ERROR_NAMES.has(name)) return false;
+  if (name === "TransactionCanceledException") return false;
+  if (name && THROTTLE_ERROR_NAMES.has(name)) return true;
+  if (name && TRANSIENT_ERROR_NAMES.has(name)) return true;
+  if (typeof error === "object" && error !== null) {
+    const retryable = error.$retryable;
+    if (retryable != null && retryable !== false) return true;
+  }
+  const status = httpStatusCode(error);
+  if (status === 429 || status != null && status >= 500) return true;
+  return false;
+}
+var THROTTLE_CANCELLATION_CODES = /* @__PURE__ */ new Set([
+  "ThrottlingError",
+  "ProvisionedThroughputExceeded",
+  "TransactionConflict"
+]);
+function isRetryableTransactionCancellation(error) {
+  if (typeof error !== "object" || error === null) return false;
+  const reasons = error.CancellationReasons;
+  if (!Array.isArray(reasons) || reasons.length === 0) return false;
+  let sawThrottle = false;
+  for (const reason of reasons) {
+    const code = reason && typeof reason === "object" ? reason.Code : void 0;
+    if (typeof code !== "string" || code === "None") {
+      continue;
+    }
+    if (code === "ConditionalCheckFailed") {
+      return false;
+    }
+    if (THROTTLE_CANCELLATION_CODES.has(code)) {
+      sawThrottle = true;
+      continue;
+    }
+    return false;
+  }
+  return sawThrottle;
+}
+function resolveRetryPolicy(override, global) {
+  if (override === false) return null;
+  const o = override ?? void 0;
+  const g = global ?? void 0;
+  const maxAttempts = o?.maxAttempts ?? g?.maxAttempts ?? DEFAULT_RETRY_POLICY.maxAttempts;
+  if (maxAttempts <= 1) return null;
+  return {
+    maxAttempts,
+    computeDelay: o?.computeDelay ?? g?.computeDelay ?? DEFAULT_RETRY_POLICY.computeDelay,
+    jitter: o?.jitter ?? g?.jitter ?? DEFAULT_RETRY_POLICY.jitter,
+    isRetryable: o?.isRetryable ?? g?.isRetryable ?? DEFAULT_RETRY_POLICY.isRetryable,
+    // onRetry has no DEFAULT (observability is opt-in): per-call wins, else global.
+    onRetry: o?.onRetry ?? g?.onRetry
+  };
+}
+function applyJitter(base, jitter) {
+  if (jitter === "none") return base;
+  return Math.random() * base;
+}
+function sleep2(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function runWithRetry(policy, operation, send, classify) {
+  if (policy === null) {
+    return send();
+  }
+  let attempt = 1;
+  for (; ; ) {
+    try {
+      return await send();
+    } catch (error) {
+      const forced = classify?.(error);
+      const retryable = forced ?? policy.isRetryable(error);
+      if (!retryable || attempt >= policy.maxAttempts) {
+        throw error;
+      }
+      const base = policy.computeDelay(attempt);
+      const delayMs = applyJitter(base, policy.jitter);
+      policy.onRetry?.({ attempt, error, delayMs, operation });
+      await sleep2(delayMs);
+      attempt += 1;
+    }
+  }
+}
+
+// src/executor/retrying-executor.ts
+var RetryingExecutor = class {
+  /**
+   * @param inner the wrapped executor (the real {@link DynamoExecutor}).
+   * @param getGlobalPolicy reads the globally-configured policy (or `null` for the
+   *   built-in default) at CALL time, so a `DDBModel.setRetryPolicy(...)` after the
+   *   executor is constructed still takes effect.
+   */
+  constructor(inner, getGlobalPolicy) {
+    this.inner = inner;
+    this.getGlobalPolicy = getGlobalPolicy;
+  }
+  inner;
+  getGlobalPolicy;
+  async execute(operation, options) {
+    const policy = resolveRetryPolicy(options?.retry, this.getGlobalPolicy());
+    const kind = operation.type === "Query" ? "query" : operation.type === "BatchGetItem" ? "batchGet" : "get";
+    return runWithRetry(policy, kind, () => this.inner.execute(operation, options));
+  }
+  async batchGet(input, options) {
+    const policy = resolveRetryPolicy(options?.retry, this.getGlobalPolicy());
+    return runWithRetry(policy, "batchGet", () => this.inner.batchGet(input, options));
+  }
+  async put(input, options) {
+    const policy = resolveRetryPolicy(options?.retry, this.getGlobalPolicy());
+    return runWithRetry(policy, "put", () => this.inner.put(input, options));
+  }
+  async update(input, options) {
+    const policy = resolveRetryPolicy(options?.retry, this.getGlobalPolicy());
+    return runWithRetry(policy, "update", () => this.inner.update(input, options));
+  }
+  async delete(input, options) {
+    const policy = resolveRetryPolicy(options?.retry, this.getGlobalPolicy());
+    return runWithRetry(policy, "delete", () => this.inner.delete(input, options));
+  }
+  async batchWrite(tableName, items, options) {
+    return this.inner.batchWrite(tableName, items, options);
+  }
+  async transactWrite(items, options) {
+    const policy = resolveRetryPolicy(options?.retry, this.getGlobalPolicy());
+    return runWithRetry(
+      policy,
+      "transactWrite",
+      () => this.inner.transactWrite(items, options),
+      (error) => errorName(error) === "TransactionCanceledException" ? isRetryableTransactionCancellation(error) : void 0
+    );
+  }
+};
+
 // src/client/ClientManager.ts
 var ClientManager = class {
   static client = null;
@@ -663,6 +846,13 @@ var ClientManager = class {
    */
   static executor = null;
   static defaultExecutor = null;
+  /**
+   * The globally-configured single-op retry policy (issue #111). `null` ⇒ the
+   * always-on built-in {@link DEFAULT_RETRY_POLICY} applies (retry is enabled out
+   * of the box). Set via {@link DDBModel.setRetryPolicy} / {@link setRetryPolicy};
+   * read at call time by the default {@link RetryingExecutor}.
+   */
+  static retryPolicy = null;
   static setClient(client) {
     this.client = client;
     this.documentClient = null;
@@ -697,23 +887,44 @@ var ClientManager = class {
       return this.executor;
     }
     if (!this.defaultExecutor) {
-      this.defaultExecutor = new DynamoExecutor();
+      this.defaultExecutor = new RetryingExecutor(
+        new DynamoExecutor(),
+        () => this.retryPolicy
+      );
     }
     return this.defaultExecutor;
   }
-  /** Inject a custom executor (test adapter / memory engine). */
+  /**
+   * Inject a custom executor (test adapter / memory engine). It is used AS-IS —
+   * not wrapped in a {@link RetryingExecutor} — so the in-memory adapter (which
+   * never throttles) bypasses the retry layer entirely (issue #111).
+   */
   static setExecutor(executor) {
     this.executor = executor;
   }
-  /** Restore the default {@link DynamoExecutor}. */
+  /** Restore the default {@link RetryingExecutor}-wrapped {@link DynamoExecutor}. */
   static resetExecutor() {
     this.executor = null;
   }
+  /**
+   * Configure the global single-op retry policy (issue #111). Mirrors
+   * {@link setClient} / {@link setTableMapping}: a process-wide setting the default
+   * {@link RetryingExecutor} reads. `null` restores the always-on built-in default.
+   * A per-call `retry?:` override on an operation option bag takes precedence.
+   */
+  static setRetryPolicy(policy) {
+    this.retryPolicy = policy;
+  }
+  /** The globally-configured retry policy, or `null` for the built-in default. */
+  static getRetryPolicy() {
+    return this.retryPolicy;
+  }
   /** @internal — for testing only */
   static reset() {
     this.client = null;
     this.documentClient = null;
     this.executor = null;
+    this.retryPolicy = null;
   }
 };
 
@@ -742,7 +953,7 @@ async function executeBatchGet(docClient, operation) {
 
 // src/executor/dynamo-executor.ts
 var DynamoExecutor = class {
-  async execute(operation) {
+  async execute(operation, _options) {
     const docClient = await ClientManager.getDocumentClient();
     if (operation.type === "GetItem") {
       return executeGetItem(docClient, operation);
@@ -752,7 +963,7 @@ var DynamoExecutor = class {
     }
     return executeQuery(docClient, operation);
   }
-  async batchGet(input) {
+  async batchGet(input, _options) {
     const docClient = await ClientManager.getDocumentClient();
     return executeBatchGet(docClient, { type: "BatchGetItem", ...input });
   }
@@ -786,7 +997,7 @@ var DynamoExecutor = class {
     );
     return toWriteResult(result);
   }
-  async batchWrite(tableName, items) {
+  async batchWrite(tableName, items, _options) {
     const docClient = await ClientManager.getDocumentClient();
     for (const chunk of chunkArray(items, BATCH_WRITE_MAX_ITEMS)) {
       await batchWriteChunkWithRetry(
@@ -798,7 +1009,7 @@ var DynamoExecutor = class {
       );
     }
   }
-  async transactWrite(items) {
+  async transactWrite(items, _options) {
     if (items.length === 0) return;
     const docClient = await ClientManager.getDocumentClient();
     const { TransactWriteCommand } = await loadLibDynamoDB();
@@ -1505,10 +1716,10 @@ function buildPutInput(modelClass, item, options) {
 async function executePut(modelClass, item, options) {
   const putInput = buildPutInput(modelClass, item, options);
   const wantsOld = ChangeCaptureRegistry.wantsOldImage(modelClass);
-  const result = await ClientManager.getExecutor().put(
-    putInput,
-    wantsOld ? { returnOldImage: true } : void 0
-  );
+  const result = await ClientManager.getExecutor().put(putInput, {
+    ...wantsOld ? { returnOldImage: true } : {},
+    ...options?.retry !== void 0 ? { retry: options.retry } : {}
+  });
   if (ChangeCaptureRegistry.hasSubscribers()) {
     const oldItem = result.oldItem;
     captureWrite({
@@ -1800,12 +2011,15 @@ function needsReadForRederive(meta, entity, serializedChanges, fieldMap) {
   return affected.some((gsi2) => missingGsiFields(gsi2, available).length > 0);
 }
 async function rederiveByReadModifyWrite(modelClass, entity, changes, options, pk, sk, tableName) {
-  const result = await ClientManager.getExecutor().execute({
-    type: "GetItem",
-    tableName,
-    keyCondition: { PK: pk, SK: sk },
-    consistentRead: true
-  });
+  const result = await ClientManager.getExecutor().execute(
+    {
+      type: "GetItem",
+      tableName,
+      keyCondition: { PK: pk, SK: sk },
+      consistentRead: true
+    },
+    options?.retry !== void 0 ? { retry: options.retry } : void 0
+  );
   const current = result.items[0];
   if (!current) {
     throw new Error(
@@ -1853,10 +2067,10 @@ async function executeUpdate(modelClass, entity, changes, options) {
     updateInput = buildUpdateInput(modelClass, entity, changes, options);
   }
   const wantsOld = ChangeCaptureRegistry.wantsOldImage(modelClass);
-  const result = await ClientManager.getExecutor().update(
-    updateInput,
-    wantsOld ? { returnOldImage: true } : void 0
-  );
+  const result = await ClientManager.getExecutor().update(updateInput, {
+    ...wantsOld ? { returnOldImage: true } : {},
+    ...options?.retry !== void 0 ? { retry: options.retry } : {}
+  });
   if (ChangeCaptureRegistry.hasSubscribers()) {
     const oldItem = result.oldItem;
     const keys = { pk: String(updateInput.Key.PK), sk: String(updateInput.Key.SK ?? "") };
@@ -1924,10 +2138,10 @@ function buildDeleteInput(modelClass, keyObj, options) {
 async function executeDelete(modelClass, keyObj, options) {
   const deleteInput = buildDeleteInput(modelClass, keyObj, options);
   const wantsOld = ChangeCaptureRegistry.wantsOldImage(modelClass);
-  const result = await ClientManager.getExecutor().delete(
-    deleteInput,
-    wantsOld ? { returnOldImage: true } : void 0
-  );
+  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({
@@ -1954,11 +2168,11 @@ function collapseSameKey(items, view) {
   for (const bucket of groups.values()) {
     if (bucket.length === 1) continue;
     const kinds = new Set(bucket.map((it) => view.kind(it)));
-    if (kinds.has("Delete") && kinds.has("Put")) {
+    if (kinds.size === 2 && kinds.has("Delete") && kinds.has("Put")) {
       for (const it of bucket) dropped.add(it);
       continue;
     }
-    if (kinds.has("Put") && kinds.has("Update")) {
+    if (kinds.size === 2 && kinds.has("Put") && kinds.has("Update")) {
       throw new Error(
         `Contract runtime: a derived counter (\`increment\`) resolves to the SAME item as the entity write at runtime (the call-time key values made an aliased target coincide with the written row). A Put+Update on one transaction item is unsupported \u2014 DynamoDB rejects touching one key twice, and collapsing it would silently drop the increment. A \`w.increment(...)\` must target a DIFFERENT row (e.g. a parent aggregate's counter); to maintain a counter ON the written entity, write the field as part of the entity itself, not via a derived counter onto its own row.`
       );
@@ -2002,7 +2216,10 @@ async function commitTransaction(items, options = {}) {
       `Transaction exceeds DynamoDB limit of ${MAX_TRANSACT_ITEMS} items`
     );
   }
-  await ClientManager.getExecutor().transactWrite(collapsed);
+  await ClientManager.getExecutor().transactWrite(
+    collapsed,
+    options.retry !== void 0 ? { retry: options.retry } : void 0
+  );
   captureTransactItems(collapsed, options.modelBySignature ?? EMPTY_MODEL_MAP);
   return collapsed;
 }
@@ -2259,6 +2476,11 @@ export {
   BATCH_GET_MAX_KEYS,
   BATCH_WRITE_MAX_ITEMS,
   DynamoExecutor,
+  DEFAULT_MAX_ATTEMPTS,
+  DEFAULT_RETRY_POLICY,
+  isRetryableError,
+  isRetryableTransactionCancellation,
+  RetryingExecutor,
   ClientManager,
   isRawCondition,
   cond,

package/dist/{chunk-CXIAECRS.js → chunk-IQEOJVHI.js}

@@ -32,7 +32,7 @@ import {
   serializeFieldValue,
   serializeRawCondition,
   skTemplate
-} from "./chunk-3MI43FHU.js";
+} from "./chunk-GCPEUPAA.js";
 
 // src/spec/types.ts
 var SPEC_VERSION = "1.0";
@@ -686,8 +686,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,7 +810,10 @@ async function executeListInternal(modelClass, key, selectSpec, options = {}) {
     updatable: options.updatable ?? false
   });
   const operation = executionPlan.operations[0];
-  const result = await execute(operation);
+  const result = await execute(
+    operation,
+    options.retry !== void 0 ? { retry: options.retry } : void 0
+  );
   const rawItems = result.items;
   const hydrated = hydrate(rawItems, select, metadata, options.updatable ?? false);
   const cursor = result.lastEvaluatedKey ? encodeCursor(result.lastEvaluatedKey) : null;
@@ -1172,7 +1175,10 @@ async function fetchBelongsToHasOneBatch(rel, rawParentItems, selectSpec, target
   const executor = ClientManager.getExecutor();
   const queryKeyToRaw = /* @__PURE__ */ new Map();
   for (const operation of batchOps) {
-    const batchResult = await executor.batchGet(operation);
+    const batchResult = await executor.batchGet(
+      operation,
+      options.retry !== void 0 ? { retry: options.retry } : void 0
+    );
     for (const item of batchResult.items) {
       for (const queryKey of queryKeys) {
         if (!matchesQueryKey(item, queryKey)) {
@@ -1272,7 +1278,8 @@ async function resolveRelations(parentItem, rawParentItem, select, metadata, opt
         after: selectSpec.after,
         order,
         filter: selectSpec.filter,
-        updatable: opts.updatable
+        updatable: opts.updatable,
+        retry: opts.retry
       });
       let items = listResult.items;
       const rawItems = listResult.rawItems;
@@ -1345,8 +1352,12 @@ 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 parentPromise = execute(
+    operation,
+    retry !== void 0 ? { retry } : void 0
+  );
+  const relationPromise = canParallelizeRelations ? resolveRelations({}, key, select, metadata, { maxDepth, updatable, retry }, 1) : null;
   let result;
   try {
     result = await parentPromise;
@@ -1373,7 +1384,7 @@ async function executeQuery(modelClass, key, selectSpec, options) {
         rawItem,
         select,
         metadata,
-        { maxDepth, updatable },
+        { maxDepth, updatable, retry },
         1
       );
       if (hydratedItem && updatable) {
@@ -1894,8 +1905,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 +2076,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) {
   const writeItems = writes.map((w) => {
     const options = w.condition !== void 0 ? { condition: w.condition } : void 0;
     let item;
@@ -2089,6 +2103,7 @@ async function executeReferentialTransaction(writes, edgeItems, updateItems, gua
     ],
     {
       modelBySignature,
+      ...retry !== void 0 ? { retry } : {},
       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.`
       )
@@ -2322,7 +2337,7 @@ async function executeCompiledWriteOp(ops, options) {
   }
   const hasDerivedEffects = renderedOps.some((r) => r.hasDerivedEffects);
   if (rendered.length === 1 && !hasDerivedEffects) {
-    await executeSingleWrite(rendered[0]);
+    await executeSingleWrite(rendered[0], options.retry);
   } else {
     await executeReferentialTransaction(
       rendered,
@@ -2333,7 +2348,8 @@ async function executeCompiledWriteOp(ops, options) {
       idempotencyItems,
       checkItems,
       label,
-      modelBySignature
+      modelBySignature,
+      options.retry
     );
   }
   const readBacks = await Promise.all(
@@ -2380,7 +2396,8 @@ 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 } : {}
         });
         results[i] = { ok: true, value: readBacks[0] };
       } catch (e) {
@@ -2459,9 +2476,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);
   }
-  return executeParallelMode(ops);
+  return executeParallelMode(ops, options.retry);
 }
 function normalizeWriteOp(alias, d) {
   if (d === null || typeof d !== "object") {
@@ -2534,10 +2551,11 @@ function mapToRefs($, fields) {
   for (const f of fields) out[f] = $[f];
   return out;
 }
-async function executeTransactionMode(ops) {
+async function executeTransactionMode(ops, retry) {
   const compiled = ops.map(compileWriteOp);
   const { readBacks } = await executeCompiledWriteOp(compiled, {
-    label: "DDBModel.mutate"
+    label: "DDBModel.mutate",
+    ...retry !== void 0 ? { retry } : {}
   });
   const out = {};
   ops.forEach((op, i) => {
@@ -2552,10 +2570,11 @@ async function executeTransactionMode(ops) {
   });
   return out;
 }
-async function executeParallelMode(ops) {
+async function executeParallelMode(ops, retry) {
   const compiled = ops.map(compileWriteOp);
   const settled = await executeCompiledParallelWrites(compiled, {
-    label: "DDBModel.mutate"
+    label: "DDBModel.mutate",
+    ...retry !== void 0 ? { retry } : {}
   });
   const out = {};
   ops.forEach((op, i) => {
@@ -2587,12 +2606,34 @@ 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);
   }
+  /**
+   * 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);
+  }
   static async transaction(fn) {
     await executeTransaction(fn);
   }

package/dist/{chunk-27XBTYVK.js → chunk-LNESVUTO.js}

@@ -1,7 +1,7 @@
 import {
   ChangeCaptureRegistry,
   resolveModelClass
-} from "./chunk-3MI43FHU.js";
+} from "./chunk-GCPEUPAA.js";
 
 // src/cdc/prng.ts
 var SeededRandom = class {

package/dist/cli.js

@@ -2,10 +2,10 @@
 import {
   buildBridgeBundle,
   normalizeSelectSpec
-} from "./chunk-CXIAECRS.js";
+} from "./chunk-IQEOJVHI.js";
 import {
   MetadataRegistry
-} from "./chunk-3MI43FHU.js";
+} from "./chunk-GCPEUPAA.js";
 
 // src/cli.ts
 import { createRequire } from "module";