@aws-blocks/bb-distributed-table 0.1.7 → 0.2.0

package/DESIGN.md

@@ -51,6 +51,8 @@ This also follows the API's options-object convention (objects over positional p
 
 `ifNotExists` and `ifFieldEquals` are mutually exclusive at the type level (discriminated union), as are `ifExists` and `ifFieldEquals`. DynamoDB's `ConditionExpression` could combine them, but the semantics are confusing — "create only if it doesn't exist AND the existing item's field equals X" is contradictory. The type system prevents this rather than silently picking one.
 
+A conditional-failure `ApiError` (409) is flagged `retriable` only for a pure `ifFieldEquals` optimistic-lock check (a re-read and retry can succeed); an existence assertion (`ifNotExists`/`ifExists`) is not retriable (a blind retry fails identically). Both runtimes derive this from a single expression keyed on **value presence** (`ifFieldEquals !== undefined`) with the **existence assertion winning** — so even the type-forbidden combined case (only reachable outside the typed API) is not retriable, and mock and AWS produce identical `retriable` for identical inputs.
+
 KVStore uses `ifValueEquals` (compare the entire value). DistributedTable uses `ifFieldEquals` (compare individual fields) because items are structured objects with multiple fields — comparing the entire item would be impractical and fragile.
 
 ### D-DT-5: `scan()` not `list()`
@@ -104,7 +106,15 @@ A generic `ValidationException` is exactly the kind of catch-all bucket worth av
 
 **Mock/AWS parity:** the mock checks serialized byte length client-side and throws `ItemTooLarge` directly. On AWS, DynamoDB raises a generic `ValidationException` for an oversized item; the runtime narrows on the size-specific message (`size has exceeded`) and re-maps only that case to `ItemTooLarge`. Other `ValidationException` causes (malformed expressions, type mismatches) propagate unchanged. Both layers therefore surface the same `error.name`, and the shared message lives in `errors.ts` (`DistributedTableMessages.itemTooLarge`) so the two stay byte-for-byte aligned.
 
-### D-DT-9: `readValidation` — `off | coerce | strict`, defaulting to `coerce`
+### D-DT-9: `retriable` on a 409 conflict is scoped to optimistic-lock (`ifFieldEquals`) only
+
+**Decision:** A `ConditionalCheckFailedException` maps to an `ApiError` with status **409**, but `retriable` is **true only for `ifFieldEquals` (optimistic-lock) conflicts** and **false for `ifNotExists`/`ifExists` (existence/uniqueness) assertions**.
+
+**Rationale:** A value/field-equals conflict is genuinely optimistic-concurrency — a re-read and retry can succeed. An `ifNotExists`/`ifExists` failure is an existence assertion: a blind identical retry fails identically, so flagging it retriable is misleading. DynamoDB collapses every conditional failure under one `ConditionalCheckFailedException` with no sub-reason, so the AWS runtime decides retriability per-operation from the condition the caller set on that specific `put`/`delete`, matching the mock branch-for-branch. `error.name` and status (409) are unchanged.
+
+Note `retriable` marks the conflict *kind* (optimistic-lock `ifFieldEquals` vs existence assertion), **not** a guarantee that a retry will succeed: an `ifFieldEquals` conflict against a **missing** row is still flagged retriable, yet a blind retry fails identically — because DynamoDB collapses missing-vs-stale into one indistinguishable exception, and the mock deliberately matches that for parity.
+
+### D-DT-10: `readValidation` — `off | coerce | strict`, defaulting to `coerce`
 
 > The **default choice** (`'coerce'` over `'off'`) is recorded as a cross-cutting architectural decision in [`docs/DECISIONS.md` D-015](../../docs/DECISIONS.md#d-015-distributedtable-reads-default-to-readvalidation-coerce-not-off). This section covers the per-BB mechanics.
 
@@ -127,7 +137,7 @@ A generic `ValidationException` is exactly the kind of catch-all bucket worth av
 
 **Mock/AWS parity:** both layers call the same `applyReadValidation()` helper in `errors.ts`, so all three modes (coerced output, raw-fallback + warn, strict throw) behave identically. `null` (a missing item) passes through untouched in every mode, preserving not-found semantics.
 
-### D-DT-10: Secure-by-default durability & encryption, sourced from stack `BlocksDefaults`
+### D-DT-11: Secure-by-default durability & encryption, sourced from stack `BlocksDefaults`
 
 Durability posture is resolved from the stack-wide `BlocksDefaults` (`BlocksPresets` in `@aws-blocks/core/cdk`), the shared infrastructure-defaults mechanism (introduced in #302): `defaults.removalPolicy`, `defaults.deletionProtection`, and `defaults.pointInTimeRecovery`. Under `BlocksPresets.production` a table defaults to PITR **on**, deletion protection **on**, and `RemovalPolicy.RETAIN`; under `BlocksPresets.sandbox` all three flip off/`DESTROY` so throwaway stacks stay cheap and `sandbox:destroy` is a one-command teardown. SSE defaults to the AWS-managed KMS key. Every default is overridable per table via `protection`, `pointInTimeRecovery`, and `encryption`; a per-block option always wins (`option ?? scope.defaults.field`). Each field is read **independently** from `defaults` — deletion protection and PITR are never derived from `removalPolicy`.
 
@@ -153,7 +163,7 @@ Creates a single DynamoDB table:
 - **TTL:** Enabled via `TimeToLiveSpecification` when `options.ttl` is set
 - **Billing mode:** PAY_PER_REQUEST
 - **Table name:** Derived from `scope.fullId` (includes stack name for uniqueness)
-- **Durability & encryption:** Secure-by-default in production — PITR, deletion protection, SSE-KMS, and `RemovalPolicy.RETAIN` (see D-DT-10)
+- **Durability & encryption:** Secure-by-default in production — PITR, deletion protection, SSE-KMS, and `RemovalPolicy.RETAIN` (see D-DT-11)
 - **Permissions:** `grantReadWriteData` to the parent scope's handler automatically, plus explicit `dynamodb:Query` on `index/*`
 
 Attribute types are inferred from the schema at synth time. The CDK layer probes the schema's `StandardSchemaV1.validate()` method with a test value of `0` for each key field — if the field accepts it without issues, it's numeric (`AttributeType.NUMBER`), otherwise string (`AttributeType.STRING`). This is schema-library-agnostic and uses only the standard validation interface.

package/README.md

@@ -129,7 +129,7 @@ await table.delete(key, { ifExists: true });
 await table.delete(key, { ifFieldEquals: { status: 'archived' } });
 ```
 
-All condition failures throw with `error.name === DistributedTableErrors.ConditionalCheckFailed`.
+All condition failures throw with `error.name === DistributedTableErrors.ConditionalCheckFailed`. They serialize to JSON-RPC **409 (Conflict)** over the wire (not 500), in both the mock and AWS runtime. Only `ifFieldEquals` optimistic-lock conflicts are flagged retriable; `ifNotExists` / `ifExists` existence assertions are **not** retriable (a blind retry fails identically).
 
 > **No partial update:** There is no `update()` or `patch()` method. To change a field, do a read-modify-write — `get()` the item, mutate it, then `put()` the full item back. For safe concurrent updates, pass `{ ifFieldEquals: { version: <previous> } }` to `put()` so the write fails (via `ConditionalCheckFailed`) if another writer changed the item in the meantime (optimistic locking).
 
@@ -178,7 +178,7 @@ Errors thrown by DistributedTable carry an `error.name` you can match with `isBl
 
 | Constant | `error.name` | Thrown when |
 |----------|--------------|-------------|
-| `DistributedTableErrors.ConditionalCheckFailed` | `ConditionalCheckFailedException` | An `ifNotExists` / `ifExists` / `ifFieldEquals` condition failed. |
+| `DistributedTableErrors.ConditionalCheckFailed` | `ConditionalCheckFailedException` | An `ifNotExists` / `ifExists` / `ifFieldEquals` condition failed. Serializes to HTTP **409 (Conflict)**; retriable only for `ifFieldEquals` optimistic-lock conflicts (not `ifNotExists` / `ifExists`). |
 | `DistributedTableErrors.ValidationFailed` | `ValidationFailedException` | An item failed the configured `schema` validation on `put()` / `putBatch()`. |
 | `DistributedTableErrors.InvalidQuery` | `InvalidQueryException` | The query/condition shape is wrong: missing `where`, partition key not given as `{ equals }`, unknown index, multiple sort-key conditions, or an empty `ifFieldEquals`. A caller bug. |
 | `DistributedTableErrors.ItemTooLarge` | `ItemTooLargeException` | A `put`/`putBatch` item exceeds DynamoDB's 400 KB per-item size limit. |

package/dist/errors.d.ts

@@ -1,4 +1,5 @@
 import type { StandardSchemaV1 } from '@standard-schema/spec';
+import { ApiError } from '@aws-blocks/core';
 import type { ChildLogger } from '@aws-blocks/bb-logger';
 import type { ReadValidationMode } from './types.js';
 /**
@@ -67,6 +68,24 @@ export declare const DistributedTableErrors: {
  * produce identically shaped errors.
  */
 export declare function blocksError(name: string, message: string): Error;
+/**
+ * @internal Build the 409 ApiError for a conditional-write conflict. Maps to
+ * HTTP 409 (Conflict) so the JSON-RPC serializer emits code 409 instead of a
+ * generic 500, preserves the `ConditionalCheckFailed` name so `isBlocksError()`
+ * keeps matching on both server and client. Shared by the mock and AWS runtime
+ * so both produce an identically shaped 409; on AWS the caught DynamoDB
+ * `ConditionalCheckFailedException` is passed as `cause` (kept server-side by
+ * ApiError).
+ *
+ * `retriable` is scoped to the assertion kind: `true` only for optimistic-lock
+ * conflicts (`ifFieldEquals`), where a re-read and retry can succeed; `false`
+ * for existence/uniqueness assertions (`ifNotExists` on put, `ifExists` on
+ * delete), where a blind identical retry fails identically. DynamoDB collapses
+ * every conditional failure under one `ConditionalCheckFailedException` with no
+ * sub-reason, so the AWS runtime decides this from the condition the caller set
+ * on that specific put/delete call.
+ */
+export declare function conditionalCheckFailed(retriable: boolean, cause?: unknown): ApiError;
 /**
  * @internal Normalize a sort-key condition before it drives a query. Shared by
  * the mock and AWS runtime so both treat the same inputs identically:

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAwBrD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,sBAAsB;;;IAGlC;;;;;;;;;;;OAWG;;IAEH;;;;;;;;;;;;OAYG;;IAEH;;;;;;;;;OASG;;CAEM,CAAC;AAEX;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,KAAK,CAIhE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,yBAAyB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC1E,SAAS,EAAE,CAAC,GAAG,SAAS,GACtB,CAAC,GAAG,SAAS,CAQf;AAED;;;;GAIG;AACH,eAAO,MAAM,wBAAwB;oCACb,MAAM,GAAG,SAAS;sCAChB,MAAM;mDAEO,MAAM;wDAED,MAAM,EAAE;;mCAI7B,MAAM;0CAEC,MAAM,aAAa,MAAM,YAAY,MAAM;CAG/D,CAAC;AAEX;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAOvD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,EAC1C,IAAI,EAAE,kBAAkB,EACxB,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC3B,IAAI,EAAE,CAAC,GAAG,IAAI,EACd,GAAG,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,EAC9B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAsBnB"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAwBrD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,sBAAsB;;;IAGlC;;;;;;;;;;;OAWG;;IAEH;;;;;;;;;;;;OAYG;;IAEH;;;;;;;;;OASG;;CAEM,CAAC;AAEX;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,KAAK,CAIhE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,QAAQ,CAMpF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,yBAAyB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC1E,SAAS,EAAE,CAAC,GAAG,SAAS,GACtB,CAAC,GAAG,SAAS,CAQf;AAED;;;;GAIG;AACH,eAAO,MAAM,wBAAwB;oCACb,MAAM,GAAG,SAAS;sCAChB,MAAM;mDAEO,MAAM;wDAED,MAAM,EAAE;;mCAI7B,MAAM;0CAEC,MAAM,aAAa,MAAM,YAAY,MAAM;CAG/D,CAAC;AAEX;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAOvD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,EAC1C,IAAI,EAAE,kBAAkB,EACxB,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC3B,IAAI,EAAE,CAAC,GAAG,IAAI,EACd,GAAG,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,EAC9B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAsBnB"}

package/dist/errors.js

@@ -1,6 +1,7 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 import { createDefu } from 'defu';
+import { ApiError } from '@aws-blocks/core';
 /**
  * @internal Right-biased deep merge for the `'coerce'` read path: overlay the
  * schema-coerced item onto the raw stored item so schema output (filled defaults,
@@ -92,6 +93,30 @@ export function blocksError(name, message) {
     err.name = name;
     return err;
 }
+/**
+ * @internal Build the 409 ApiError for a conditional-write conflict. Maps to
+ * HTTP 409 (Conflict) so the JSON-RPC serializer emits code 409 instead of a
+ * generic 500, preserves the `ConditionalCheckFailed` name so `isBlocksError()`
+ * keeps matching on both server and client. Shared by the mock and AWS runtime
+ * so both produce an identically shaped 409; on AWS the caught DynamoDB
+ * `ConditionalCheckFailedException` is passed as `cause` (kept server-side by
+ * ApiError).
+ *
+ * `retriable` is scoped to the assertion kind: `true` only for optimistic-lock
+ * conflicts (`ifFieldEquals`), where a re-read and retry can succeed; `false`
+ * for existence/uniqueness assertions (`ifNotExists` on put, `ifExists` on
+ * delete), where a blind identical retry fails identically. DynamoDB collapses
+ * every conditional failure under one `ConditionalCheckFailedException` with no
+ * sub-reason, so the AWS runtime decides this from the condition the caller set
+ * on that specific put/delete call.
+ */
+export function conditionalCheckFailed(retriable, cause) {
+    return new ApiError('The conditional request failed', 409, {
+        name: DistributedTableErrors.ConditionalCheckFailed,
+        cause,
+        retriable,
+    });
+}
 /**
  * @internal Normalize a sort-key condition before it drives a query. Shared by
  * the mock and AWS runtime so both treat the same inputs identically:

package/dist/index.aws.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.aws.d.ts","sourceRoot":"","sources":["../src/index.aws.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.aws.d.ts","sourceRoot":"","sources":["../src/index.aws.ts"],"names":[],"mappings":"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"}

package/dist/index.aws.js

@@ -5,7 +5,7 @@ import { DynamoDBDocumentClient, GetCommand, PutCommand, DeleteCommand, QueryCom
 import { Scope, registerSdkIdentifiers, getSdkIdentifiers } from '@aws-blocks/core';
 import { BB_NAME, BB_VERSION } from './version.js';
 export { DistributedTableErrors } from './errors.js';
-import { DistributedTableErrors, DistributedTableMessages, blocksError, normalizeSortKeyCondition, remapItemTooLarge, applyReadValidation } from './errors.js';
+import { DistributedTableErrors, DistributedTableMessages, blocksError, conditionalCheckFailed, normalizeSortKeyCondition, remapItemTooLarge, applyReadValidation } from './errors.js';
 import { Logger } from '@aws-blocks/bb-logger';
 // ── Helpers ─────────────────────────────────────────────────────────────────
 // DynamoDB batch API limits and retry tuning.
@@ -75,6 +75,21 @@ export class DistributedTable extends Scope {
             await this.docClient.send(new PutCommand(command));
         }
         catch (err) {
+            // A failed conditional write is a Conflict, not an
+            // InternalServerError: map DynamoDB's raw
+            // ConditionalCheckFailedException to an ApiError with status 409 so the
+            // JSON-RPC serializer emits code 409 instead of 500. Name is preserved
+            // for isBlocksError(), the driver error is kept as `cause`. DynamoDB
+            // collapses every conditional failure under one exception with no
+            // sub-reason, so retriability is derived from the conditions THIS call
+            // set, matching the mock: existence assertion wins — retriable only for
+            // a pure `ifFieldEquals` optimistic-lock check (value presence, so an
+            // explicit `undefined` is treated as absent) and NOT when `ifNotExists`
+            // is also set. Other errors (e.g. oversized items) still flow through
+            // remapItemTooLarge.
+            if (err instanceof Error && err.name === DistributedTableErrors.ConditionalCheckFailed) {
+                throw conditionalCheckFailed(options?.ifFieldEquals !== undefined && !options?.ifNotExists, err);
+            }
             throw remapItemTooLarge(err);
         }
     }
@@ -87,7 +102,22 @@ export class DistributedTable extends Scope {
         else if (options?.ifFieldEquals) {
             this.applyFieldEqualsCondition(command, options.ifFieldEquals);
         }
-        await this.docClient.send(new DeleteCommand(command));
+        try {
+            await this.docClient.send(new DeleteCommand(command));
+        }
+        catch (err) {
+            // A failed conditional delete is a Conflict, not an
+            // InternalServerError: map DynamoDB's raw
+            // ConditionalCheckFailedException to an ApiError with status 409 (see
+            // the put path above). Retriability is derived from the conditions THIS
+            // call set, matching the mock: existence assertion wins — retriable only
+            // for a pure `ifFieldEquals` optimistic-lock check (value presence) and
+            // NOT when `ifExists` is also set.
+            if (err instanceof Error && err.name === DistributedTableErrors.ConditionalCheckFailed) {
+                throw conditionalCheckFailed(options?.ifFieldEquals !== undefined && !options?.ifExists, err);
+            }
+            throw err;
+        }
     }
     /**
      * Query items by index, yielding matches as an async stream with automatic

package/dist/index.cdk.d.ts

@@ -1,9 +1,9 @@
-import { Scope } from '@aws-blocks/core/cdk';
+import { BuildingBlockScope } from '@aws-blocks/core/cdk';
 import type { ScopeParent } from '@aws-blocks/core';
 import type { ExternalTableRef, ExternalKmsKeyRef } from './types.js';
 export { DistributedTableErrors } from './errors.js';
 export type { DistributedTableOptions, ReadValidationMode, TableKeyConfig, TableKey, PutOptions, DeleteOptions, QueryOptions, ScanOptions, ExternalTableRef, ExternalKmsKeyRef } from './types.js';
-export declare class DistributedTable<T = any> extends Scope {
+export declare class DistributedTable<T = any> extends BuildingBlockScope {
     options: any;
     private table;
     /**

package/dist/index.cdk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.cdk.d.ts","sourceRoot":"","sources":["../src/index.cdk.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,KAAK,EAAoC,MAAM,sBAAsB,CAAC;AAC/E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAItE,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AACrD,YAAY,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,cAAc,EAAE,QAAQ,EAAE,UAAU,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEnM,qBAAa,gBAAgB,CAAC,CAAC,GAAG,GAAG,CAAE,SAAQ,KAAK;IA2BA,OAAO,EAAE,GAAG;IA1B/D,OAAO,CAAC,KAAK,CAAS;IAEtB;;;;;;OAMG;IACH,MAAM,CAAC,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB;IAIxD;;;;;;;;OAQG;IACH,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB;gBAIxC,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,EAAS,OAAO,EAAE,GAAG;IAqO/D,GAAG,CAAC,GAAG,KAAK,EAAE,OAAO,EAAE,GAAG,KAAK;IAC/B,GAAG,CAAC,GAAG,KAAK,EAAE,OAAO,EAAE,GAAG,KAAK;IAC/B,MAAM,CAAC,GAAG,KAAK,EAAE,OAAO,EAAE,GAAG,KAAK;IAClC,KAAK,CAAC,GAAG,KAAK,EAAE,OAAO,EAAE,GAAG,KAAK;IACjC,IAAI,CAAC,GAAG,KAAK,EAAE,OAAO,EAAE,GAAG,KAAK;IAChC,QAAQ,CAAC,GAAG,KAAK,EAAE,OAAO,EAAE,GAAG,KAAK;IACpC,QAAQ,CAAC,GAAG,KAAK,EAAE,OAAO,EAAE,GAAG,KAAK;IACpC,WAAW,CAAC,GAAG,KAAK,EAAE,OAAO,EAAE,GAAG,KAAK;CACvC"}
+{"version":3,"file":"index.cdk.d.ts","sourceRoot":"","sources":["../src/index.cdk.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,kBAAkB,EAAoC,MAAM,sBAAsB,CAAC;AAC5F,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAItE,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AACrD,YAAY,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,cAAc,EAAE,QAAQ,EAAE,UAAU,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEnM,qBAAa,gBAAgB,CAAC,CAAC,GAAG,GAAG,CAAE,SAAQ,kBAAkB;IA2Bb,OAAO,EAAE,GAAG;IA1B/D,OAAO,CAAC,KAAK,CAAS;IAEtB;;;;;;OAMG;IACH,MAAM,CAAC,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB;IAIxD;;;;;;;;OAQG;IACH,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB;gBAIxC,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,EAAS,OAAO,EAAE,GAAG;IAqO/D,GAAG,CAAC,GAAG,KAAK,EAAE,OAAO,EAAE,GAAG,KAAK;IAC/B,GAAG,CAAC,GAAG,KAAK,EAAE,OAAO,EAAE,GAAG,KAAK;IAC/B,MAAM,CAAC,GAAG,KAAK,EAAE,OAAO,EAAE,GAAG,KAAK;IAClC,KAAK,CAAC,GAAG,KAAK,EAAE,OAAO,EAAE,GAAG,KAAK;IACjC,IAAI,CAAC,GAAG,KAAK,EAAE,OAAO,EAAE,GAAG,KAAK;IAChC,QAAQ,CAAC,GAAG,KAAK,EAAE,OAAO,EAAE,GAAG,KAAK;IACpC,QAAQ,CAAC,GAAG,KAAK,EAAE,OAAO,EAAE,GAAG,KAAK;IACpC,WAAW,CAAC,GAAG,KAAK,EAAE,OAAO,EAAE,GAAG,KAAK;CACvC"}

package/dist/index.cdk.js

@@ -1,6 +1,7 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 import { Table, AttributeType, BillingMode, TableEncryption } from 'aws-cdk-lib/aws-dynamodb';
+import * as ec2 from 'aws-cdk-lib/aws-ec2';
 import * as cdk from 'aws-cdk-lib';
 import { Annotations, CustomResource, Duration, RemovalPolicy } from 'aws-cdk-lib';
 import { Code, Function as LambdaFunction } from 'aws-cdk-lib/aws-lambda';
@@ -8,11 +9,11 @@ import { LogGroup } from 'aws-cdk-lib/aws-logs';
 import { Provider } from 'aws-cdk-lib/custom-resources';
 import { PolicyStatement } from 'aws-cdk-lib/aws-iam';
 import { Key } from 'aws-cdk-lib/aws-kms';
-import { Scope, synthGuard, DEFAULT_NODE_RUNTIME } from '@aws-blocks/core/cdk';
+import { BuildingBlockScope, synthGuard, DEFAULT_NODE_RUNTIME } from '@aws-blocks/core/cdk';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
 export { DistributedTableErrors } from './errors.js';
-export class DistributedTable extends Scope {
+export class DistributedTable extends BuildingBlockScope {
     options;
     table;
     /**
@@ -38,7 +39,7 @@ export class DistributedTable extends Scope {
         return { __brand: 'ExternalKmsKeyRef', keyArn };
     }
     constructor(scope, id, options) {
-        super(id, { parent: scope });
+        super(id, { parent: scope, vpc: { gatewayEndpoints: [ec2.GatewayVpcEndpointAwsService.DYNAMODB] } });
         this.options = options;
         const config = options;
         if (config?.table) {

package/dist/index.mock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.mock.d.ts","sourceRoot":"","sources":["../src/index.mock.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.mock.d.ts","sourceRoot":"","sources":["../src/index.mock.ts"],"names":[],"mappings":"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"}

package/dist/index.mock.js

@@ -6,7 +6,7 @@ import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { BB_NAME, BB_VERSION } from './version.js';
 export { DistributedTableErrors } from './errors.js';
-import { DistributedTableErrors, DistributedTableMessages, blocksError, normalizeSortKeyCondition, applyReadValidation } from './errors.js';
+import { DistributedTableErrors, DistributedTableMessages, blocksError, conditionalCheckFailed, normalizeSortKeyCondition, applyReadValidation } from './errors.js';
 // ── Helpers ─────────────────────────────────────────────────────────────────
 const MAX_ITEM_BYTES = 400 * 1024;
 async function validateSchema(schema, value) {
@@ -131,22 +131,31 @@ export class DistributedTable extends Scope {
             throw blocksError(DistributedTableErrors.ItemTooLarge, DistributedTableMessages.itemTooLarge(Buffer.byteLength(serialized, 'utf8')));
         }
         const keyStr = this.serializeKey(item);
+        // Existence assertion wins: `ifNotExists` makes a conflict non-retriable
+        // even if combined with an `ifFieldEquals` value check (value presence, so
+        // an explicit `undefined` is treated as absent). Only a pure `ifFieldEquals`
+        // optimistic-lock check is retriable. Shared derivation so mock and aws
+        // agree for identical inputs, incl. combined conditions.
+        const retriable = options?.ifFieldEquals !== undefined && !options?.ifNotExists;
         if (options?.ifNotExists && this.data.has(keyStr)) {
-            throw blocksError(DistributedTableErrors.ConditionalCheckFailed, 'The conditional request failed');
+            throw conditionalCheckFailed(retriable);
         }
         if (options?.ifFieldEquals) {
-            this.checkFieldEquals(keyStr, options.ifFieldEquals);
+            this.checkFieldEquals(keyStr, options.ifFieldEquals, retriable);
         }
         this.data.set(keyStr, item);
         this.flushToDisk();
     }
     async delete(key, options) {
         const keyStr = this.serializeKey(key);
+        // Existence assertion wins (see put): `ifExists` makes a conflict
+        // non-retriable even if combined with an `ifFieldEquals` value check.
+        const retriable = options?.ifFieldEquals !== undefined && !options?.ifExists;
         if (options?.ifExists && !this.data.has(keyStr)) {
-            throw blocksError(DistributedTableErrors.ConditionalCheckFailed, 'The conditional request failed');
+            throw conditionalCheckFailed(retriable);
         }
         if (options?.ifFieldEquals) {
-            this.checkFieldEquals(keyStr, options.ifFieldEquals);
+            this.checkFieldEquals(keyStr, options.ifFieldEquals, retriable);
         }
         this.data.delete(keyStr);
         this.flushToDisk();
@@ -287,18 +296,21 @@ export class DistributedTable extends Scope {
         return { __brand: 'ExternalKmsKeyRef', keyArn };
     }
     // ── Internal ────────────────────────────────────────────────────────────
-    checkFieldEquals(keyStr, fields) {
+    checkFieldEquals(keyStr, fields, retriable) {
         const entries = Object.entries(fields).filter(([, v]) => v !== undefined);
         if (entries.length === 0) {
             throw blocksError(DistributedTableErrors.InvalidQuery, DistributedTableMessages.emptyIfFieldEquals);
         }
         const existing = this.data.get(keyStr);
         if (!existing) {
-            throw blocksError(DistributedTableErrors.ConditionalCheckFailed, 'The conditional request failed');
+            // Compare-and-swap conflict; retriability is decided by the caller —
+            // existence assertion wins, so not retriable even if combined.
+            throw conditionalCheckFailed(retriable);
         }
         for (const [field, value] of entries) {
             if (!deepEqual(existing[field], value)) {
-                throw blocksError(DistributedTableErrors.ConditionalCheckFailed, 'The conditional request failed');
+                // Compare-and-swap conflict; retriability decided by the caller.
+                throw conditionalCheckFailed(retriable);
             }
         }
     }

package/dist/index.test.js

@@ -3,7 +3,7 @@
 import { test, describe } from 'node:test';
 import { strict as assert } from 'node:assert';
 import { DistributedTable, DistributedTableErrors } from './index.mock.js';
-import { Scope } from '@aws-blocks/core';
+import { ApiError, isBlocksError, Scope } from '@aws-blocks/core';
 import { z } from 'zod';
 // ── Schemas ─────────────────────────────────────────────────────────────────
 const userSchema = z.object({
@@ -117,6 +117,89 @@ describe('DistributedTable', () => {
             await assert.rejects(() => table.put({ userId: 'u1', email: 'a@b.com', name: 'Fail', createdAt: 1000 }, { ifFieldEquals: { name: 'Wrong' } }), (err) => err.name === DistributedTableErrors.ConditionalCheckFailed);
         });
     });
+    // ── OCC conflicts map to HTTP 409 (Conflict) ─────────────────────────────
+    // A conditional-write conflict must serialize to JSON-RPC code 409, not 500.
+    // The mock must throw an ApiError (status 409) that preserves the
+    // ConditionalCheckFailed name, matching the aws-runtime path. `retriable` is
+    // scoped to the assertion kind: true only for optimistic-lock ifFieldEquals
+    // conflicts (a re-read and retry can succeed), false for existence/uniqueness
+    // assertions (a blind retry fails identically).
+    describe('OCC conflicts map to 409', () => {
+        test('put ifNotExists conflict is an ApiError with status 409, not retriable', async () => {
+            const table = new DistributedTable(testScope(), 'users', {
+                schema: userSchema,
+                key: { partitionKey: 'userId', sortKey: 'createdAt' },
+            });
+            const user = { userId: 'user1', email: 'test@example.com', name: 'Test', createdAt: 1000 };
+            await table.put(user);
+            await assert.rejects(() => table.put(user, { ifNotExists: true }), (err) => {
+                assert.ok(err instanceof ApiError, `expected an ApiError, got ${err}`);
+                assert.equal(err.status, 409);
+                assert.ok(isBlocksError(err, DistributedTableErrors.ConditionalCheckFailed));
+                assert.equal(err.retriable, false);
+                return true;
+            });
+        });
+        test('put ifFieldEquals conflict is an ApiError with status 409, retriable', async () => {
+            const table = new DistributedTable(testScope(), 'users', {
+                schema: userSchema,
+                key: { partitionKey: 'userId', sortKey: 'createdAt' },
+            });
+            await table.put({ userId: 'u1', email: 'a@b.com', name: 'Test', createdAt: 1000 });
+            await assert.rejects(() => table.put({ userId: 'u1', email: 'a@b.com', name: 'Fail', createdAt: 1000 }, { ifFieldEquals: { name: 'Wrong' } }), (err) => {
+                assert.ok(err instanceof ApiError, `expected an ApiError, got ${err}`);
+                assert.equal(err.status, 409);
+                assert.ok(isBlocksError(err, DistributedTableErrors.ConditionalCheckFailed));
+                assert.equal(err.retriable, true);
+                return true;
+            });
+        });
+        test('put ifNotExists + ifFieldEquals conflict is 409, not retriable (existence wins)', async () => {
+            const table = new DistributedTable(testScope(), 'users', {
+                schema: userSchema,
+                key: { partitionKey: 'userId', sortKey: 'createdAt' },
+            });
+            await table.put({ userId: 'u1', email: 'a@b.com', name: 'Test', createdAt: 1000 });
+            // The typed API forbids combining ifNotExists with ifFieldEquals; force
+            // the combined shape to verify the runtime derivation is existence-wins
+            // (not retriable) for parity with the aws path and bb-kv-store.
+            const combined = { ifNotExists: true, ifFieldEquals: { name: 'Wrong' } };
+            await assert.rejects(() => table.put({ userId: 'u1', email: 'a@b.com', name: 'Fail', createdAt: 1000 }, combined), (err) => {
+                assert.ok(err instanceof ApiError, `expected an ApiError, got ${err}`);
+                assert.equal(err.status, 409);
+                assert.ok(isBlocksError(err, DistributedTableErrors.ConditionalCheckFailed));
+                assert.equal(err.retriable, false);
+                return true;
+            });
+        });
+        test('delete ifExists conflict is an ApiError with status 409, not retriable', async () => {
+            const table = new DistributedTable(testScope(), 'users', {
+                schema: userSchema,
+                key: { partitionKey: 'userId', sortKey: 'createdAt' },
+            });
+            await assert.rejects(() => table.delete({ userId: 'missing', createdAt: 1 }, { ifExists: true }), (err) => {
+                assert.ok(err instanceof ApiError, `expected an ApiError, got ${err}`);
+                assert.equal(err.status, 409);
+                assert.ok(isBlocksError(err, DistributedTableErrors.ConditionalCheckFailed));
+                assert.equal(err.retriable, false);
+                return true;
+            });
+        });
+        test('delete ifFieldEquals conflict is an ApiError with status 409, retriable', async () => {
+            const table = new DistributedTable(testScope(), 'users', {
+                schema: userSchema,
+                key: { partitionKey: 'userId', sortKey: 'createdAt' },
+            });
+            await table.put({ userId: 'u1', email: 'a@b.com', name: 'Test', createdAt: 1000 });
+            await assert.rejects(() => table.delete({ userId: 'u1', createdAt: 1000 }, { ifFieldEquals: { name: 'Wrong' } }), (err) => {
+                assert.ok(err instanceof ApiError, `expected an ApiError, got ${err}`);
+                assert.equal(err.status, 409);
+                assert.ok(isBlocksError(err, DistributedTableErrors.ConditionalCheckFailed));
+                assert.equal(err.retriable, true);
+                return true;
+            });
+        });
+    });
     // ── Conditional delete ──────────────────────────────────────────────────
     describe('conditional delete', () => {
         test('ifExists succeeds when item exists', async () => {

package/dist/version.d.ts

@@ -1,3 +1,3 @@
 export declare const BB_NAME = "DistributedTable";
-export declare const BB_VERSION = "0.1.7";
+export declare const BB_VERSION = "0.2.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1,3 +1,3 @@
 // Auto-generated by scripts/generate-version.mjs — do not edit manually
 export const BB_NAME = 'DistributedTable';
-export const BB_VERSION = '0.1.7';
+export const BB_VERSION = '0.2.0';

package/package.json

@@ -1,6 +1,12 @@
 {
   "name": "@aws-blocks/bb-distributed-table",
-  "version": "0.1.7",
+  "version": "0.2.0",
+  "keywords": [
+    "aws-blocks",
+    "dynamodb",
+    "nosql",
+    "database"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/aws-devtools-labs/aws-blocks.git",
@@ -39,8 +45,8 @@
     "test": "node --test --test-concurrency=1 dist/index.test.js dist/parity.test.js dist/index.cdk.test.js"
   },
   "dependencies": {
-    "@aws-blocks/core": "^0.4.0",
-    "@aws-blocks/bb-logger": "^0.1.6",
+    "@aws-blocks/core": "^0.5.0",
+    "@aws-blocks/bb-logger": "^0.2.0",
     "@aws-sdk/client-dynamodb": "^3.0.0",
     "@aws-sdk/lib-dynamodb": "^3.0.0",
     "@standard-schema/spec": "^1.0.0",

package/src/errors.ts

@@ -3,6 +3,7 @@
 
 import { createDefu } from 'defu';
 import type { StandardSchemaV1 } from '@standard-schema/spec';
+import { ApiError } from '@aws-blocks/core';
 import type { ChildLogger } from '@aws-blocks/bb-logger';
 import type { ReadValidationMode } from './types.js';
 
@@ -100,6 +101,31 @@ export function blocksError(name: string, message: string): Error {
 	return err;
 }
 
+/**
+ * @internal Build the 409 ApiError for a conditional-write conflict. Maps to
+ * HTTP 409 (Conflict) so the JSON-RPC serializer emits code 409 instead of a
+ * generic 500, preserves the `ConditionalCheckFailed` name so `isBlocksError()`
+ * keeps matching on both server and client. Shared by the mock and AWS runtime
+ * so both produce an identically shaped 409; on AWS the caught DynamoDB
+ * `ConditionalCheckFailedException` is passed as `cause` (kept server-side by
+ * ApiError).
+ *
+ * `retriable` is scoped to the assertion kind: `true` only for optimistic-lock
+ * conflicts (`ifFieldEquals`), where a re-read and retry can succeed; `false`
+ * for existence/uniqueness assertions (`ifNotExists` on put, `ifExists` on
+ * delete), where a blind identical retry fails identically. DynamoDB collapses
+ * every conditional failure under one `ConditionalCheckFailedException` with no
+ * sub-reason, so the AWS runtime decides this from the condition the caller set
+ * on that specific put/delete call.
+ */
+export function conditionalCheckFailed(retriable: boolean, cause?: unknown): ApiError {
+	return new ApiError('The conditional request failed', 409, {
+		name: DistributedTableErrors.ConditionalCheckFailed,
+		cause,
+		retriable,
+	});
+}
+
 /**
  * @internal Normalize a sort-key condition before it drives a query. Shared by
  * the mock and AWS runtime so both treat the same inputs identically:

package/src/index.aws.ts

@@ -47,7 +47,7 @@ import type {
 	TableKey,
 	ReadValidationMode,
 } from './types.js';
-import { DistributedTableErrors, DistributedTableMessages, blocksError, normalizeSortKeyCondition, remapItemTooLarge, applyReadValidation } from './errors.js';
+import { DistributedTableErrors, DistributedTableMessages, blocksError, conditionalCheckFailed, normalizeSortKeyCondition, remapItemTooLarge, applyReadValidation } from './errors.js';
 import type { KeyCondition, QueryOptions } from './types.js';
 import { Logger } from '@aws-blocks/bb-logger';
 import type { ChildLogger } from '@aws-blocks/bb-logger';
@@ -129,6 +129,21 @@ export class DistributedTable<
 		try {
 			await this.docClient.send(new PutCommand(command));
 		} catch (err: unknown) {
+			// A failed conditional write is a Conflict, not an
+			// InternalServerError: map DynamoDB's raw
+			// ConditionalCheckFailedException to an ApiError with status 409 so the
+			// JSON-RPC serializer emits code 409 instead of 500. Name is preserved
+			// for isBlocksError(), the driver error is kept as `cause`. DynamoDB
+			// collapses every conditional failure under one exception with no
+			// sub-reason, so retriability is derived from the conditions THIS call
+			// set, matching the mock: existence assertion wins — retriable only for
+			// a pure `ifFieldEquals` optimistic-lock check (value presence, so an
+			// explicit `undefined` is treated as absent) and NOT when `ifNotExists`
+			// is also set. Other errors (e.g. oversized items) still flow through
+			// remapItemTooLarge.
+			if (err instanceof Error && err.name === DistributedTableErrors.ConditionalCheckFailed) {
+				throw conditionalCheckFailed(options?.ifFieldEquals !== undefined && !options?.ifNotExists, err);
+			}
 			throw remapItemTooLarge(err);
 		}
 	}
@@ -143,7 +158,21 @@ export class DistributedTable<
 			this.applyFieldEqualsCondition(command, options.ifFieldEquals);
 		}
 
-		await this.docClient.send(new DeleteCommand(command));
+		try {
+			await this.docClient.send(new DeleteCommand(command));
+		} catch (err: unknown) {
+			// A failed conditional delete is a Conflict, not an
+			// InternalServerError: map DynamoDB's raw
+			// ConditionalCheckFailedException to an ApiError with status 409 (see
+			// the put path above). Retriability is derived from the conditions THIS
+			// call set, matching the mock: existence assertion wins — retriable only
+			// for a pure `ifFieldEquals` optimistic-lock check (value presence) and
+			// NOT when `ifExists` is also set.
+			if (err instanceof Error && err.name === DistributedTableErrors.ConditionalCheckFailed) {
+				throw conditionalCheckFailed(options?.ifFieldEquals !== undefined && !options?.ifExists, err);
+			}
+			throw err;
+		}
 	}
 
 	/**

package/src/index.cdk.ts

@@ -3,6 +3,7 @@
 
 import { Construct } from 'constructs';
 import { Table, type ITable, AttributeType, BillingMode, TableEncryption } from 'aws-cdk-lib/aws-dynamodb';
+import * as ec2 from 'aws-cdk-lib/aws-ec2';
 import * as cdk from 'aws-cdk-lib';
 import { Annotations, CustomResource, Duration, RemovalPolicy } from 'aws-cdk-lib';
 import { Code, Function as LambdaFunction } from 'aws-cdk-lib/aws-lambda';
@@ -10,7 +11,7 @@ import { LogGroup, type RetentionDays } from 'aws-cdk-lib/aws-logs';
 import { Provider } from 'aws-cdk-lib/custom-resources';
 import { PolicyStatement } from 'aws-cdk-lib/aws-iam';
 import { Key, type IKey } from 'aws-cdk-lib/aws-kms';
-import { Scope, synthGuard, DEFAULT_NODE_RUNTIME } from '@aws-blocks/core/cdk';
+import { BuildingBlockScope, synthGuard, DEFAULT_NODE_RUNTIME } from '@aws-blocks/core/cdk';
 import type { ScopeParent } from '@aws-blocks/core';
 import type { ExternalTableRef, ExternalKmsKeyRef } from './types.js';
 import { fileURLToPath } from 'node:url';
@@ -19,7 +20,7 @@ import { dirname, join } from 'node:path';
 export { DistributedTableErrors } from './errors.js';
 export type { DistributedTableOptions, ReadValidationMode, TableKeyConfig, TableKey, PutOptions, DeleteOptions, QueryOptions, ScanOptions, ExternalTableRef, ExternalKmsKeyRef } from './types.js';
 
-export class DistributedTable<T = any> extends Scope {
+export class DistributedTable<T = any> extends BuildingBlockScope {
 	private table: ITable;
 
 	/**
@@ -47,7 +48,7 @@ export class DistributedTable<T = any> extends Scope {
 	}
 
 	constructor(scope: ScopeParent, id: string, public options: any) {
-		super(id, { parent: scope });
+		super(id, { parent: scope, vpc: { gatewayEndpoints: [ec2.GatewayVpcEndpointAwsService.DYNAMODB] } });
 
 		const config = options;
 

package/src/index.mock.ts

@@ -38,7 +38,7 @@ import type {
 	TableKey,
 	ReadValidationMode,
 } from './types.js';
-import { DistributedTableErrors, DistributedTableMessages, blocksError, normalizeSortKeyCondition, applyReadValidation } from './errors.js';
+import { DistributedTableErrors, DistributedTableMessages, blocksError, conditionalCheckFailed, normalizeSortKeyCondition, applyReadValidation } from './errors.js';
 
 // ── Helpers ─────────────────────────────────────────────────────────────────
 
@@ -173,13 +173,18 @@ export class DistributedTable<
 
 		const keyStr = this.serializeKey(item as any);
 
+		// Existence assertion wins: `ifNotExists` makes a conflict non-retriable
+		// even if combined with an `ifFieldEquals` value check (value presence, so
+		// an explicit `undefined` is treated as absent). Only a pure `ifFieldEquals`
+		// optimistic-lock check is retriable. Shared derivation so mock and aws
+		// agree for identical inputs, incl. combined conditions.
+		const retriable = options?.ifFieldEquals !== undefined && !options?.ifNotExists;
 		if (options?.ifNotExists && this.data.has(keyStr)) {
-			throw blocksError(DistributedTableErrors.ConditionalCheckFailed, 'The conditional request failed');
+			throw conditionalCheckFailed(retriable);
 		}
 		if (options?.ifFieldEquals) {
-			this.checkFieldEquals(keyStr, options.ifFieldEquals);
+			this.checkFieldEquals(keyStr, options.ifFieldEquals, retriable);
 		}
-
 		this.data.set(keyStr, item);
 		this.flushToDisk();
 	}
@@ -187,11 +192,14 @@ export class DistributedTable<
 	async delete(key: TableKey<T, K>, options?: DeleteOptions<T>): Promise<void> {
 		const keyStr = this.serializeKey(key);
 
+		// Existence assertion wins (see put): `ifExists` makes a conflict
+		// non-retriable even if combined with an `ifFieldEquals` value check.
+		const retriable = options?.ifFieldEquals !== undefined && !options?.ifExists;
 		if (options?.ifExists && !this.data.has(keyStr)) {
-			throw blocksError(DistributedTableErrors.ConditionalCheckFailed, 'The conditional request failed');
+			throw conditionalCheckFailed(retriable);
 		}
 		if (options?.ifFieldEquals) {
-			this.checkFieldEquals(keyStr, options.ifFieldEquals);
+			this.checkFieldEquals(keyStr, options.ifFieldEquals, retriable);
 		}
 
 		this.data.delete(keyStr);
@@ -349,7 +357,7 @@ export class DistributedTable<
 
 	// ── Internal ────────────────────────────────────────────────────────────
 
-	private checkFieldEquals(keyStr: string, fields: Partial<T>): void {
+	private checkFieldEquals(keyStr: string, fields: Partial<T>, retriable: boolean): void {
 		const entries = Object.entries(fields).filter(([, v]) => v !== undefined);
 		if (entries.length === 0) {
 			throw blocksError(DistributedTableErrors.InvalidQuery, DistributedTableMessages.emptyIfFieldEquals);
@@ -357,11 +365,14 @@ export class DistributedTable<
 
 		const existing = this.data.get(keyStr);
 		if (!existing) {
-			throw blocksError(DistributedTableErrors.ConditionalCheckFailed, 'The conditional request failed');
+			// Compare-and-swap conflict; retriability is decided by the caller —
+			// existence assertion wins, so not retriable even if combined.
+			throw conditionalCheckFailed(retriable);
 		}
 		for (const [field, value] of entries) {
 			if (!deepEqual((existing as any)[field], value)) {
-				throw blocksError(DistributedTableErrors.ConditionalCheckFailed, 'The conditional request failed');
+				// Compare-and-swap conflict; retriability decided by the caller.
+				throw conditionalCheckFailed(retriable);
 			}
 		}
 	}

package/src/index.test.ts

@@ -4,7 +4,7 @@
 import { test, describe } from 'node:test';
 import { strict as assert } from 'node:assert';
 import { DistributedTable, DistributedTableErrors } from './index.mock.js';
-import { Scope } from '@aws-blocks/core';
+import { ApiError, isBlocksError, Scope } from '@aws-blocks/core';
 import { z } from 'zod';
 
 // ── Schemas ─────────────────────────────────────────────────────────────────
@@ -143,6 +143,110 @@ describe('DistributedTable', () => {
 		});
 	});
 
+	// ── OCC conflicts map to HTTP 409 (Conflict) ─────────────────────────────
+	// A conditional-write conflict must serialize to JSON-RPC code 409, not 500.
+	// The mock must throw an ApiError (status 409) that preserves the
+	// ConditionalCheckFailed name, matching the aws-runtime path. `retriable` is
+	// scoped to the assertion kind: true only for optimistic-lock ifFieldEquals
+	// conflicts (a re-read and retry can succeed), false for existence/uniqueness
+	// assertions (a blind retry fails identically).
+
+	describe('OCC conflicts map to 409', () => {
+		test('put ifNotExists conflict is an ApiError with status 409, not retriable', async () => {
+			const table = new DistributedTable(testScope(), 'users', {
+				schema: userSchema,
+				key: { partitionKey: 'userId', sortKey: 'createdAt' },
+			});
+			const user = { userId: 'user1', email: 'test@example.com', name: 'Test', createdAt: 1000 };
+			await table.put(user);
+			await assert.rejects(
+				() => table.put(user, { ifNotExists: true }),
+				(err: unknown) => {
+					assert.ok(err instanceof ApiError, `expected an ApiError, got ${err}`);
+					assert.equal(err.status, 409);
+					assert.ok(isBlocksError(err, DistributedTableErrors.ConditionalCheckFailed));
+					assert.equal(err.retriable, false);
+					return true;
+				},
+			);
+		});
+
+		test('put ifFieldEquals conflict is an ApiError with status 409, retriable', async () => {
+			const table = new DistributedTable(testScope(), 'users', {
+				schema: userSchema,
+				key: { partitionKey: 'userId', sortKey: 'createdAt' },
+			});
+			await table.put({ userId: 'u1', email: 'a@b.com', name: 'Test', createdAt: 1000 });
+			await assert.rejects(
+				() => table.put({ userId: 'u1', email: 'a@b.com', name: 'Fail', createdAt: 1000 }, { ifFieldEquals: { name: 'Wrong' } }),
+				(err: unknown) => {
+					assert.ok(err instanceof ApiError, `expected an ApiError, got ${err}`);
+					assert.equal(err.status, 409);
+					assert.ok(isBlocksError(err, DistributedTableErrors.ConditionalCheckFailed));
+					assert.equal(err.retriable, true);
+					return true;
+				},
+			);
+		});
+
+		test('put ifNotExists + ifFieldEquals conflict is 409, not retriable (existence wins)', async () => {
+			const table = new DistributedTable(testScope(), 'users', {
+				schema: userSchema,
+				key: { partitionKey: 'userId', sortKey: 'createdAt' },
+			});
+			await table.put({ userId: 'u1', email: 'a@b.com', name: 'Test', createdAt: 1000 });
+			// The typed API forbids combining ifNotExists with ifFieldEquals; force
+			// the combined shape to verify the runtime derivation is existence-wins
+			// (not retriable) for parity with the aws path and bb-kv-store.
+			const combined = { ifNotExists: true, ifFieldEquals: { name: 'Wrong' } } as unknown as Parameters<typeof table.put>[1];
+			await assert.rejects(
+				() => table.put({ userId: 'u1', email: 'a@b.com', name: 'Fail', createdAt: 1000 }, combined),
+				(err: unknown) => {
+					assert.ok(err instanceof ApiError, `expected an ApiError, got ${err}`);
+					assert.equal(err.status, 409);
+					assert.ok(isBlocksError(err, DistributedTableErrors.ConditionalCheckFailed));
+					assert.equal(err.retriable, false);
+					return true;
+				},
+			);
+		});
+
+		test('delete ifExists conflict is an ApiError with status 409, not retriable', async () => {
+			const table = new DistributedTable(testScope(), 'users', {
+				schema: userSchema,
+				key: { partitionKey: 'userId', sortKey: 'createdAt' },
+			});
+			await assert.rejects(
+				() => table.delete({ userId: 'missing', createdAt: 1 }, { ifExists: true }),
+				(err: unknown) => {
+					assert.ok(err instanceof ApiError, `expected an ApiError, got ${err}`);
+					assert.equal(err.status, 409);
+					assert.ok(isBlocksError(err, DistributedTableErrors.ConditionalCheckFailed));
+					assert.equal(err.retriable, false);
+					return true;
+				},
+			);
+		});
+
+		test('delete ifFieldEquals conflict is an ApiError with status 409, retriable', async () => {
+			const table = new DistributedTable(testScope(), 'users', {
+				schema: userSchema,
+				key: { partitionKey: 'userId', sortKey: 'createdAt' },
+			});
+			await table.put({ userId: 'u1', email: 'a@b.com', name: 'Test', createdAt: 1000 });
+			await assert.rejects(
+				() => table.delete({ userId: 'u1', createdAt: 1000 }, { ifFieldEquals: { name: 'Wrong' } }),
+				(err: unknown) => {
+					assert.ok(err instanceof ApiError, `expected an ApiError, got ${err}`);
+					assert.equal(err.status, 409);
+					assert.ok(isBlocksError(err, DistributedTableErrors.ConditionalCheckFailed));
+					assert.equal(err.retriable, true);
+					return true;
+				},
+			);
+		});
+	});
+
 	// ── Conditional delete ──────────────────────────────────────────────────
 
 	describe('conditional delete', () => {

package/src/version.ts

@@ -1,3 +1,3 @@
 // Auto-generated by scripts/generate-version.mjs — do not edit manually
 export const BB_NAME = 'DistributedTable';
-export const BB_VERSION = '0.1.7';
+export const BB_VERSION = '0.2.0';