@aws-blocks/bb-distributed-table 0.1.6 → 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()`
@@ -81,6 +83,10 @@ orders.query({
 
 The `order` field maps to DynamoDB's `ScanIndexForward` parameter (`'desc'` → `ScanIndexForward: false`). It defaults to `'asc'`.
 
+**Ordering ties (GSI):** a GSI sort key need not be unique, so multiple items can share one sort-key value. The mock tie-breaks on the base-table primary key (partition key, then sort key) rather than on Map insertion order — otherwise results would depend on write order / disk-reload order. This **matches DynamoDB's observed ordering** for index rows with equal sort keys; AWS does not document a contractual guarantee for the tie order, so the mock is intentionally **deterministic even where DynamoDB's contract is unspecified** (a plus for reproducible tests — just don't rely on a specific tie order in production logic). Under `order: 'desc'` the whole index order, ties included, reverses.
+
+**String-ordering boundary:** the mock compares sort/base keys with JavaScript `<`/`>` (UTF-16 code-unit order), which can differ from DynamoDB's UTF-8 byte order for non-ASCII string keys. This applies to both the index sort-key comparison and the base-key tie-break, and is a pre-existing property of the mock — surfaced here so the parity discussion is complete.
+
 ### D-DT-7: TTL via options field
 
 **Decision:** TTL is configured via `ttl: 'fieldName'` in the constructor options, not as a separate method or decorator.
@@ -100,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.
 
@@ -123,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`.
 
@@ -149,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":"AAcA,OAAO,EAAE,KAAK,EAA6C,MAAM,kBAAkB,CAAC;AACpF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAIpD,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AACrD,YAAY,EACX,cAAc,EACd,uBAAuB,EACvB,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EACjB,QAAQ,EACR,qBAAqB,EACrB,gBAAgB,EAChB,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,UAAU,EACV,aAAa,GACb,MAAM,YAAY,CAAC;AAEpB,OAAO,KAAK,EACX,cAAc,EACd,uBAAuB,EACvB,gBAAgB,EAChB,iBAAiB,EACjB,WAAW,EACX,UAAU,EACV,aAAa,EAGb,QAAQ,EAER,MAAM,YAAY,CAAC;AAEpB,OAAO,KAAK,EAAgB,YAAY,EAAE,MAAM,YAAY,CAAC;AAE7D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAwBzD,qBAAa,gBAAgB,CAC5B,CAAC,EACD,CAAC,SAAS,cAAc,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,EAC/C,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC,CACpF,SAAQ,KAAK;IAWqC,OAAO,EAAE,uBAAuB,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC;IAVlG,QAAQ,CAAC,MAAM,sBAAW;IAC1B,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,SAAS,CAAI;IACrB,OAAO,CAAC,OAAO,CAAU;IACzB,OAAO,CAAC,cAAc,CAAqB;IAC3C,OAAO,CAAC,SAAS,CAAyB;IAE1C,0FAA0F;IAC1F,SAAS,CAAC,GAAG,EAAE,WAAW,CAAC;gBAEf,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,EAAS,OAAO,EAAE,uBAAuB,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC;IAkB5F,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAQ3C,GAAG,CAAC,IAAI,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBpD,MAAM,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAa5E;;;;;;;;OAQG;IACI,KAAK,CACX,OAAO,EAAE,YAAY,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,GAClC,aAAa,CAAC,CAAC,CAAC;IAsCZ,IAAI,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,CAAC,CAAC;IAoB9C,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC;IAwBvD,QAAQ,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAsBnC,WAAW,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBxD,MAAM,CAAC,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB;IAIxD,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB;YAMtC,YAAY;IAQ1B;;;;;OAKG;IACH,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,QAAQ;IAMhB,OAAO,CAAC,OAAO;IAWf;;;;;;;;;;;;;;;OAeG;YACW,gBAAgB;IAkB9B,OAAO,CAAC,yBAAyB;IAkBjC,OAAO,CAAC,iBAAiB;CA4CzB"}
+{"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":"AAWA,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,17 +1,19 @@
 // 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';
+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;
     /**
@@ -37,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) {
@@ -207,7 +209,7 @@ export class DistributedTable extends Scope {
         }));
         // Add GSI manager if indexes are defined
         if (config.indexes && Object.keys(config.indexes).length > 0) {
-            const gsiProvider = getOrCreateGsiProvider(cdk.Stack.of(this));
+            const gsiProvider = getOrCreateGsiProvider(cdk.Stack.of(this), this.defaults.logRetention);
             gsiProvider.addTableArn(this.table.tableArn, isSandbox);
             const indexesWithTypes = {};
             for (const [indexName, indexConfig] of Object.entries(config.indexes)) {
@@ -249,24 +251,35 @@ export class DistributedTable extends Scope {
 }
 // ── Shared GSI Manager Provider (one per stack) ─────────────────────────────
 const GSI_PROVIDER_KEY = Symbol.for('BLOCKS_GSI_MANAGER_PROVIDER');
-function getOrCreateGsiProvider(stack) {
+function getOrCreateGsiProvider(stack, logRetention) {
     const existing = stack[GSI_PROVIDER_KEY];
     if (existing)
         return existing;
     const __dirname = dirname(fileURLToPath(import.meta.url));
     const tableArns = [];
     const sandboxTableArns = [];
+    // Own the GSI-manager Lambdas' log groups so their retention follows the
+    // stack-wide default instead of AWS's infinite retention. Torn down with the
+    // stack (logs are not durable state).
     const gsiManagerLambda = new LambdaFunction(stack, 'BlocksGsiManager', {
         runtime: DEFAULT_NODE_RUNTIME,
         handler: 'index.handler',
         code: Code.fromAsset(join(__dirname, 'gsi-manager-lambda')),
         timeout: Duration.minutes(15),
+        logGroup: new LogGroup(stack, 'BlocksGsiManagerLogs', {
+            retention: logRetention,
+            removalPolicy: cdk.RemovalPolicy.DESTROY,
+        }),
     });
     const gsiIsCompleteLambda = new LambdaFunction(stack, 'BlocksGsiIsComplete', {
         runtime: DEFAULT_NODE_RUNTIME,
         handler: 'index.isCompleteHandler',
         code: Code.fromAsset(join(__dirname, 'gsi-manager-lambda')),
         timeout: Duration.minutes(1),
+        logGroup: new LogGroup(stack, 'BlocksGsiIsCompleteLogs', {
+            retention: logRetention,
+            removalPolicy: cdk.RemovalPolicy.DESTROY,
+        }),
     });
     // Production permissions — lazily resolved so ARNs accumulate as tables register
     gsiManagerLambda.addToRolePolicy(new PolicyStatement({

package/dist/index.cdk.test.js

@@ -332,6 +332,19 @@ test('CDK: a per-block protection option overrides the stack defaults', () => {
     template.hasResource('AWS::DynamoDB::Table', { DeletionPolicy: 'Retain' });
     template.hasResourceProperties('AWS::DynamoDB::Table', { DeletionProtectionEnabled: true });
 });
+test('CDK: GSI manager Lambda log groups adopt defaults.logRetention', () => {
+    const { stack, parent } = setup(BlocksPresets.sandbox);
+    new DistributedTable(parent, 'users', {
+        schema: userSchema,
+        key: { partitionKey: 'userId', sortKey: 'createdAt' },
+        indexes: { byEmail: { partitionKey: 'email' } },
+    });
+    const template = Template.fromStack(stack);
+    // The GSI manager + isComplete Lambdas now own explicit log groups whose
+    // retention follows the stack-wide default (sandbox → one week), instead of
+    // AWS's infinite default.
+    template.hasResourceProperties('AWS::Logs::LogGroup', { RetentionInDays: 7 });
+});
 test('CDK: DistributedTable.fromExisting does NOT provision a table (regression)', () => {
     const { stack, parent } = setup();
     new DistributedTable(parent, 'users', {

package/dist/index.mock.d.ts

@@ -101,6 +101,13 @@ export declare class DistributedTable<T, K extends TableKeyConfig<T> = TableKeyC
     static fromExisting(tableName: string): ExternalTableRef;
     static fromKmsKey(keyArn: string): ExternalKmsKeyRef;
     private checkFieldEquals;
+    /**
+     * Deterministic tie-break for `query` ordering: compare two items by the
+     * base-table primary key (partition key, then sort key). Used when an index
+     * sort-key value is shared by multiple items, so results don't depend on Map
+     * insertion order. Returns a stable -1/0/1.
+     */
+    private compareByBaseKey;
     private serializeKey;
     private loadFromDisk;
     private flushToDisk;

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();
@@ -212,7 +221,14 @@ export class DistributedTable extends Scope {
             const dir = options.order === 'desc' ? -1 : 1;
             items.sort((a, b) => {
                 const av = a[skField], bv = b[skField];
-                return (av < bv ? -1 : av > bv ? 1 : 0) * dir;
+                const primary = av < bv ? -1 : av > bv ? 1 : 0;
+                // Tie-break on the base-table primary key. On a GSI the sort key need
+                // not be unique, so equal sort-key values must NOT fall back to Map
+                // insertion order (which varies by write order / disk reload) — that's
+                // the mock-vs-DynamoDB divergence. DynamoDB orders index ties by the
+                // base-table key, and the whole index (ties included) reverses under
+                // `order: 'desc'`.
+                return (primary !== 0 ? primary : this.compareByBaseKey(a, b)) * dir;
             });
         }
         let count = 0;
@@ -280,21 +296,46 @@ 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);
             }
         }
     }
+    /**
+     * Deterministic tie-break for `query` ordering: compare two items by the
+     * base-table primary key (partition key, then sort key). Used when an index
+     * sort-key value is shared by multiple items, so results don't depend on Map
+     * insertion order. Returns a stable -1/0/1.
+     */
+    compareByBaseKey(a, b) {
+        const pk = this.keyConfig.partitionKey;
+        const ap = a[pk], bp = b[pk];
+        if (ap !== bp)
+            return ap < bp ? -1 : 1;
+        const sk = this.keyConfig.sortKey;
+        if (sk) {
+            const as = a[sk], bs = b[sk];
+            if (as !== bs)
+                return as < bs ? -1 : 1;
+        }
+        // Unreachable for distinct rows: every item is keyed by its serialized base
+        // primary key, so two different entries always differ in base PK or SK.
+        // (String comparisons above use JS UTF-16 order — see DESIGN.md D-DT-6.)
+        return 0;
+    }
     serializeKey(key) {
         const parts = [key[this.keyConfig.partitionKey]];
         if (this.keyConfig.sortKey)

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 () => {
@@ -724,4 +807,46 @@ describe('DistributedTable', () => {
             async () => { for await (const _ of table.query({ index: 'doesNotExist', where: { userId: { equals: 'u1' } } })) { } }, /Index 'doesNotExist' not found/);
         });
     });
+    // ── Query: index sort-key ties are ordered deterministically ────────────
+    describe('query (index sort-key ties)', () => {
+        const cardSchema = z.object({ boardId: z.string(), cardId: z.string(), position: z.number() });
+        // Base key is (boardId, cardId); the GSI sorts by `position`, which is NOT
+        // unique — several cards can share a position. DynamoDB tie-breaks such
+        // index rows by the base-table key, so the mock must too (not by Map
+        // insertion order, which varies by write order / disk reload).
+        function cardTable() {
+            return new DistributedTable(testScope(), 'cards', {
+                schema: cardSchema,
+                key: { partitionKey: 'boardId', sortKey: 'cardId' },
+                indexes: { byPosition: { partitionKey: 'boardId', sortKey: 'position' } },
+            });
+        }
+        const q = (t, order) => collect(t.query({ index: 'byPosition', where: { boardId: { equals: 'b1' } }, ...(order ? { order } : {}) }));
+        test('ties on the index sort key order by the base-table key, regardless of write order', async () => {
+            const t1 = cardTable();
+            // All position=1; insert cardIds out of order.
+            for (const cardId of ['c3', 'c1', 'c2'])
+                await t1.put({ boardId: 'b1', cardId, position: 1 });
+            assert.deepEqual((await q(t1)).map((c) => c.cardId), ['c1', 'c2', 'c3']);
+            // A different write order must yield the SAME result (deterministic).
+            const t2 = cardTable();
+            for (const cardId of ['c2', 'c3', 'c1'])
+                await t2.put({ boardId: 'b1', cardId, position: 1 });
+            assert.deepEqual((await q(t2)).map((c) => c.cardId), ['c1', 'c2', 'c3']);
+        });
+        test('desc reverses ties too (whole index order flips)', async () => {
+            const t = cardTable();
+            for (const cardId of ['c1', 'c3', 'c2'])
+                await t.put({ boardId: 'b1', cardId, position: 1 });
+            assert.deepEqual((await q(t, 'desc')).map((c) => c.cardId), ['c3', 'c2', 'c1']);
+        });
+        test('primary order stays by index sort key; base key only breaks ties', async () => {
+            const t = cardTable();
+            await t.put({ boardId: 'b1', cardId: 'zzz', position: 1 });
+            await t.put({ boardId: 'b1', cardId: 'aaa', position: 2 });
+            await t.put({ boardId: 'b1', cardId: 'mmm', position: 1 });
+            // position asc first (1,1,2); within position=1, base key (cardId) breaks the tie.
+            assert.deepEqual((await q(t)).map((c) => [c.position, c.cardId]), [[1, 'mmm'], [1, 'zzz'], [2, 'aaa']]);
+        });
+    });
 });

package/dist/version.d.ts

@@ -1,3 +1,3 @@
 export declare const BB_NAME = "DistributedTable";
-export declare const BB_VERSION = "0.1.6";
+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.6';
+export const BB_VERSION = '0.2.0';

package/package.json

@@ -1,6 +1,12 @@
 {
   "name": "@aws-blocks/bb-distributed-table",
-  "version": "0.1.6",
+  "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.3.0",
-    "@aws-blocks/bb-logger": "^0.1.5",
+    "@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.test.ts

@@ -363,6 +363,20 @@ test('CDK: a per-block protection option overrides the stack defaults', () => {
 	template.hasResourceProperties('AWS::DynamoDB::Table', { DeletionProtectionEnabled: true });
 });
 
+test('CDK: GSI manager Lambda log groups adopt defaults.logRetention', () => {
+	const { stack, parent } = setup(BlocksPresets.sandbox);
+	new DistributedTable(parent, 'users', {
+		schema: userSchema,
+		key: { partitionKey: 'userId', sortKey: 'createdAt' },
+		indexes: { byEmail: { partitionKey: 'email' } },
+	});
+	const template = Template.fromStack(stack);
+	// The GSI manager + isComplete Lambdas now own explicit log groups whose
+	// retention follows the stack-wide default (sandbox → one week), instead of
+	// AWS's infinite default.
+	template.hasResourceProperties('AWS::Logs::LogGroup', { RetentionInDays: 7 });
+});
+
 test('CDK: DistributedTable.fromExisting does NOT provision a table (regression)', () => {
 	const { stack, parent } = setup();
 	new DistributedTable(parent, 'users', {

package/src/index.cdk.ts

@@ -3,13 +3,15 @@
 
 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';
+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';
@@ -18,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;
 
 	/**
@@ -46,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;
 
@@ -239,7 +241,7 @@ export class DistributedTable<T = any> extends Scope {
 
 		// Add GSI manager if indexes are defined
 		if (config.indexes && Object.keys(config.indexes).length > 0) {
-			const gsiProvider = getOrCreateGsiProvider(cdk.Stack.of(this));
+			const gsiProvider = getOrCreateGsiProvider(cdk.Stack.of(this), this.defaults.logRetention);
 			gsiProvider.addTableArn(this.table.tableArn, isSandbox);
 
 			const indexesWithTypes: Record<string, any> = {};
@@ -293,7 +295,7 @@ interface SharedGsiProvider {
 	addTableArn: (tableArn: string, isSandbox: boolean) => void;
 }
 
-function getOrCreateGsiProvider(stack: cdk.Stack): SharedGsiProvider {
+function getOrCreateGsiProvider(stack: cdk.Stack, logRetention: RetentionDays): SharedGsiProvider {
 	const existing = (stack as any)[GSI_PROVIDER_KEY] as SharedGsiProvider | undefined;
 	if (existing) return existing;
 
@@ -302,11 +304,18 @@ function getOrCreateGsiProvider(stack: cdk.Stack): SharedGsiProvider {
 	const tableArns: string[] = [];
 	const sandboxTableArns: string[] = [];
 
+	// Own the GSI-manager Lambdas' log groups so their retention follows the
+	// stack-wide default instead of AWS's infinite retention. Torn down with the
+	// stack (logs are not durable state).
 	const gsiManagerLambda = new LambdaFunction(stack, 'BlocksGsiManager', {
 		runtime: DEFAULT_NODE_RUNTIME,
 		handler: 'index.handler',
 		code: Code.fromAsset(join(__dirname, 'gsi-manager-lambda')),
 		timeout: Duration.minutes(15),
+		logGroup: new LogGroup(stack, 'BlocksGsiManagerLogs', {
+			retention: logRetention,
+			removalPolicy: cdk.RemovalPolicy.DESTROY,
+		}),
 	});
 
 	const gsiIsCompleteLambda = new LambdaFunction(stack, 'BlocksGsiIsComplete', {
@@ -314,6 +323,10 @@ function getOrCreateGsiProvider(stack: cdk.Stack): SharedGsiProvider {
 		handler: 'index.isCompleteHandler',
 		code: Code.fromAsset(join(__dirname, 'gsi-manager-lambda')),
 		timeout: Duration.minutes(1),
+		logGroup: new LogGroup(stack, 'BlocksGsiIsCompleteLogs', {
+			retention: logRetention,
+			removalPolicy: cdk.RemovalPolicy.DESTROY,
+		}),
 	});
 
 	// Production permissions — lazily resolved so ARNs accumulate as tables register

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);
@@ -266,7 +274,14 @@ export class DistributedTable<
 			const dir = options.order === 'desc' ? -1 : 1;
 			items.sort((a, b) => {
 				const av = (a as any)[skField], bv = (b as any)[skField];
-				return (av < bv ? -1 : av > bv ? 1 : 0) * dir;
+				const primary = av < bv ? -1 : av > bv ? 1 : 0;
+				// Tie-break on the base-table primary key. On a GSI the sort key need
+				// not be unique, so equal sort-key values must NOT fall back to Map
+				// insertion order (which varies by write order / disk reload) — that's
+				// the mock-vs-DynamoDB divergence. DynamoDB orders index ties by the
+				// base-table key, and the whole index (ties included) reverses under
+				// `order: 'desc'`.
+				return (primary !== 0 ? primary : this.compareByBaseKey(a, b)) * dir;
 			});
 		}
 
@@ -342,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);
@@ -350,15 +365,39 @@ 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);
 			}
 		}
 	}
 
+	/**
+	 * Deterministic tie-break for `query` ordering: compare two items by the
+	 * base-table primary key (partition key, then sort key). Used when an index
+	 * sort-key value is shared by multiple items, so results don't depend on Map
+	 * insertion order. Returns a stable -1/0/1.
+	 */
+	private compareByBaseKey(a: T, b: T): number {
+		const pk = this.keyConfig.partitionKey;
+		const ap = (a as any)[pk], bp = (b as any)[pk];
+		if (ap !== bp) return ap < bp ? -1 : 1;
+		const sk = this.keyConfig.sortKey;
+		if (sk) {
+			const as = (a as any)[sk], bs = (b as any)[sk];
+			if (as !== bs) return as < bs ? -1 : 1;
+		}
+		// Unreachable for distinct rows: every item is keyed by its serialized base
+		// primary key, so two different entries always differ in base PK or SK.
+		// (String comparisons above use JS UTF-16 order — see DESIGN.md D-DT-6.)
+		return 0;
+	}
+
 	private serializeKey(key: TableKey<T, K>): string {
 		const parts = [(key as any)[this.keyConfig.partitionKey]];
 		if (this.keyConfig.sortKey) parts.push((key as any)[this.keyConfig.sortKey]);

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', () => {
@@ -859,4 +963,49 @@ describe('DistributedTable', () => {
 			);
 		});
 	});
+
+	// ── Query: index sort-key ties are ordered deterministically ────────────
+	describe('query (index sort-key ties)', () => {
+		const cardSchema = z.object({ boardId: z.string(), cardId: z.string(), position: z.number() });
+		// Base key is (boardId, cardId); the GSI sorts by `position`, which is NOT
+		// unique — several cards can share a position. DynamoDB tie-breaks such
+		// index rows by the base-table key, so the mock must too (not by Map
+		// insertion order, which varies by write order / disk reload).
+		function cardTable() {
+			return new DistributedTable(testScope(), 'cards', {
+				schema: cardSchema,
+				key: { partitionKey: 'boardId', sortKey: 'cardId' },
+				indexes: { byPosition: { partitionKey: 'boardId', sortKey: 'position' } },
+			});
+		}
+		const q = (t: ReturnType<typeof cardTable>, order?: 'asc' | 'desc') =>
+			collect(t.query({ index: 'byPosition', where: { boardId: { equals: 'b1' } }, ...(order ? { order } : {}) }));
+
+		test('ties on the index sort key order by the base-table key, regardless of write order', async () => {
+			const t1 = cardTable();
+			// All position=1; insert cardIds out of order.
+			for (const cardId of ['c3', 'c1', 'c2']) await t1.put({ boardId: 'b1', cardId, position: 1 });
+			assert.deepEqual((await q(t1)).map((c) => c.cardId), ['c1', 'c2', 'c3']);
+
+			// A different write order must yield the SAME result (deterministic).
+			const t2 = cardTable();
+			for (const cardId of ['c2', 'c3', 'c1']) await t2.put({ boardId: 'b1', cardId, position: 1 });
+			assert.deepEqual((await q(t2)).map((c) => c.cardId), ['c1', 'c2', 'c3']);
+		});
+
+		test('desc reverses ties too (whole index order flips)', async () => {
+			const t = cardTable();
+			for (const cardId of ['c1', 'c3', 'c2']) await t.put({ boardId: 'b1', cardId, position: 1 });
+			assert.deepEqual((await q(t, 'desc')).map((c) => c.cardId), ['c3', 'c2', 'c1']);
+		});
+
+		test('primary order stays by index sort key; base key only breaks ties', async () => {
+			const t = cardTable();
+			await t.put({ boardId: 'b1', cardId: 'zzz', position: 1 });
+			await t.put({ boardId: 'b1', cardId: 'aaa', position: 2 });
+			await t.put({ boardId: 'b1', cardId: 'mmm', position: 1 });
+			// position asc first (1,1,2); within position=1, base key (cardId) breaks the tie.
+			assert.deepEqual((await q(t)).map((c) => [c.position, c.cardId]), [[1, 'mmm'], [1, 'zzz'], [2, 'aaa']]);
+		});
+	});
 });

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.6';
+export const BB_VERSION = '0.2.0';