@aws-blocks/bb-distributed-data 0.1.8 → 0.2.0

package/DESIGN.md

@@ -47,7 +47,7 @@ bb-distributed-data (this package)
 - PGlite wrapped with a validation layer
 - `validateStatement()` rejects unsupported SQL before execution
 - `TransactionTracker` enforces DDL/DML separation and 3,000-row limit
-- `simulateConflict()` test helper for OCC testing
+- `simulateConflict()` test helper for OCC unit testing (mock-only hook, absent from the deployed AWS surface). The `40001`→409 serialization-conflict mapping is covered by translator/engine **unit tests** (mirroring `bb-data`), not an over-the-wire e2e test: `simulateConflict()` is a mock-only trigger with no counterpart on the deployed runtime, and there is no deterministic way to raise a genuine `40001` conflict over the JSON-RPC wire in local e2e. A duplicate-key `23505`→409 `UniqueConstraintViolation` conflict (not retriable) is different: the DSQL mock enforces the primary-key constraint, so it **is** deterministically inducible over the wire and is additionally covered by an over-the-wire e2e test (`test-apps/comprehensive/test/dsql.test.ts`), not a mock-only hook.
 - Error translation matches production behavior
 
 ## Validation Layer
@@ -128,7 +128,7 @@ Happens in the engine layer (same pattern as bb-data engines):
 | pg error code | DistributedDatabaseErrors name |
 |---------------|------------------------|
 | `40001` | `SerializationFailure` |
-| `23505` | `UniqueConstraintViolation` |
+| `23505` | `UniqueConstraintViolation` (→ `ApiError` 409, not retriable) |
 | `08xxx` | `ConnectionFailed` |
 | (other) | `QueryFailed` |
 

package/README.md

@@ -36,7 +36,7 @@ const { rowCount } = await db.execute(
 DSQL uses OCC — transactions may fail at commit if another transaction modified the same rows. The callback executes exactly once unless you opt into retry.
 
 ```typescript
-// Default: no retry. Throws SerializationFailureException on conflict.
+// Default: no retry. Throws SerializationFailureException (HTTP 409 Conflict, retriable) on conflict.
 await db.transaction(async (tx) => {
   await tx.execute(sql`UPDATE accounts SET balance = balance - ${100} WHERE id = ${fromId}`);
   await tx.execute(sql`UPDATE accounts SET balance = balance + ${100} WHERE id = ${toId}`);
@@ -157,10 +157,12 @@ try {
   await db.transaction(async (tx) => { /* ... */ });
 } catch (e: unknown) {
   if (isBlocksError(e, DistributedDatabaseErrors.SerializationFailure)) {
-    // OCC conflict — transaction was NOT committed. Safe to retry.
+    // OCC conflict — transaction was NOT committed. Serialized as HTTP 409
+    // (Conflict), retriable — safe to retry.
   }
   if (isBlocksError(e, DistributedDatabaseErrors.UniqueConstraintViolation)) {
-    // Duplicate key
+    // Duplicate key — serialized as HTTP 409 (Conflict), not retriable
+    // (a blind retry of the same insert fails identically).
   }
   if (isBlocksError(e, DistributedDatabaseErrors.QueryFailed)) {
     // General query failure

package/dist/engines/dsql-mock-engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dsql-mock-engine.d.ts","sourceRoot":"","sources":["../../src/engines/dsql-mock-engine.ts"],"names":[],"mappings":"AAGA;;GAEG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAG9C,OAAO,EAA6B,KAAK,cAAc,EAAE,KAAK,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAoCjH,qBAAa,cAAe,YAAW,cAAc;IACnD,OAAO,CAAC,EAAE,CAAS;IACnB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA8B;IAC3D,OAAO,CAAC,KAAK,CAAC,CAAkB;IAEhC;;;;;OAKG;gBACS,OAAO,EAAE,MAAM,EAAE,YAAY,GAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAiC;IAMjG,OAAO,CAAC,QAAQ;IAMhB;;;;;OAKG;IACH,OAAO,CAAC,WAAW;IA6BnB,yDAAyD;IACzD,gBAAgB,IAAI,IAAI;IAExB;;;OAGG;IACG,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAK5C,KAAK,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAMvD,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAMvE,gBAAgB,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAQ9C,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAc3D,mBAAmB,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAK7D,kBAAkB,CAAC,CAAC,EAAE,MAAM,EAAE,iBAAiB,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAO/F,oBAAoB,CAAC,MAAM,EAAE,iBAAiB,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAW/G,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAK/B"}
+{"version":3,"file":"dsql-mock-engine.d.ts","sourceRoot":"","sources":["../../src/engines/dsql-mock-engine.ts"],"names":[],"mappings":"AAGA;;GAEG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAG9C,OAAO,EAA6B,KAAK,cAAc,EAAE,KAAK,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAoCjH,qBAAa,cAAe,YAAW,cAAc;IACnD,OAAO,CAAC,EAAE,CAAS;IACnB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA8B;IAC3D,OAAO,CAAC,KAAK,CAAC,CAAkB;IAEhC;;;;;OAKG;gBACS,OAAO,EAAE,MAAM,EAAE,YAAY,GAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAiC;IAMjG,OAAO,CAAC,QAAQ;IAMhB;;;;;OAKG;IACH,OAAO,CAAC,WAAW;IA6BnB,yDAAyD;IACzD,gBAAgB,IAAI,IAAI;IAExB;;;OAGG;IACG,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAK5C,KAAK,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAMvD,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAMvE,gBAAgB,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAQ9C,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAiB3D,mBAAmB,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAK7D,kBAAkB,CAAC,CAAC,EAAE,MAAM,EAAE,iBAAiB,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAO/F,oBAAoB,CAAC,MAAM,EAAE,iBAAiB,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAW/G,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAK/B"}

package/dist/engines/dsql-mock-engine.js

@@ -148,7 +148,10 @@ export class DsqlMockEngine {
             this.shouldConflict = false;
             await this.db.query('ROLLBACK');
             const err = Object.assign(new Error('SerializationFailureException: OCC conflict — transaction not committed.'), { code: PG_SERIALIZATION_FAILURE, name: DistributedDatabaseErrors.SerializationFailure });
-            throw err;
+            // Route through translateDsqlError so the mock surfaces the SAME 409
+            // ApiError (name preserved, retriable) the real DSQL engine produces for
+            // SQLSTATE 40001 — keeping mock and aws paths behaviorally identical.
+            translateDsqlError(err);
         }
         await this.db.query('COMMIT');
         handle.tracker.reset();

package/dist/engines/dsql-mock-engine.test.js

@@ -7,6 +7,7 @@ import { rmSync } from 'node:fs';
 import { join } from 'node:path';
 import { DsqlMockEngine } from './dsql-mock-engine.js';
 import { DistributedDatabaseErrors } from '../errors.js';
+import { ApiError } from '@aws-blocks/core';
 const TEST_DIR = '.bb-data-dsql-mock-test-' + process.pid;
 let engine;
 afterEach(async () => {
@@ -110,3 +111,21 @@ test('recovers on a later call after the init-retry budget is exhausted', async
     assert.deepStrictEqual(rows, [{ id: 'ok' }]);
     assert.ok(creates >= 4, 'engine should build a fresh instance after exhaustion');
 });
+// --- OCC conflict surfaces as HTTP 409 (Conflict) ---
+// A simulated serialization-failure (SQLSTATE 40001) on commit must reach the
+// caller as an ApiError with status 409 — not a plain 500 — while preserving
+// the SerializationFailure name and flagging the conflict retriable, so mock
+// and real DSQL engines behave identically over the JSON-RPC wire.
+test('commit OCC conflict surfaces as an ApiError with status 409', async () => {
+    const dir = join(TEST_DIR, 'occ-conflict-409');
+    engine = new DsqlMockEngine(dir);
+    const handle = await engine.beginTransaction();
+    engine.simulateConflict();
+    await assert.rejects(() => engine.commitTransaction(handle), (e) => {
+        assert.ok(e instanceof ApiError, 'expected an ApiError');
+        assert.strictEqual(e.status, 409);
+        assert.strictEqual(e.name, DistributedDatabaseErrors.SerializationFailure);
+        assert.strictEqual(e.retriable, true);
+        return true;
+    });
+});

package/dist/errors.d.ts

@@ -1,3 +1,4 @@
+import { ApiError } from '@aws-blocks/core';
 /**
  * DSQL-specific error constants.
  */
@@ -24,6 +25,37 @@ export declare const PG_CONNECTION_EXCEPTION_CLASS = "08";
  * @see https://docs.aws.amazon.com/aurora-dsql/latest/userguide/working-with-transactions.html
  */
 export declare const TRANSACTION_ROW_LIMIT = 3000;
+/**
+ * Build the 409 ApiError for a serialization-failure (SQLSTATE 40001) OCC
+ * conflict. Maps to HTTP 409 (Conflict) so the JSON-RPC serializer emits code
+ * 409 instead of a generic 500, preserves the `SerializationFailure` name so
+ * `isBlocksError(e, DistributedDatabaseErrors.SerializationFailure)` keeps
+ * matching on both server and client, keeps the original engine error as
+ * `cause` (server-side), and flags the conflict retriable — the caller can
+ * retry the transaction (see `retryOnConflict`).
+ *
+ * The client-visible message is a fixed, stable string (the raw driver text is
+ * verbose); the original error is retained as `cause` for server-side
+ * diagnostics.
+ */
+export declare function serializationConflict(cause: Error): ApiError;
+/**
+ * Build the 409 ApiError for a unique-constraint / duplicate-key violation
+ * (SQLSTATE 23505). Maps to HTTP 409 (Conflict) so the JSON-RPC serializer emits
+ * code 409 instead of a generic 500, preserves the `UniqueConstraintViolation`
+ * name so `isBlocksError(e, DistributedDatabaseErrors.UniqueConstraintViolation)`
+ * keeps matching on both server and client, and keeps the original engine error
+ * as `cause` (server-side).
+ *
+ * Unlike {@link serializationConflict}, this is NOT flagged retriable: a
+ * duplicate key is a deterministic constraint failure, so a blind retry of the
+ * same insert fails identically (ApiError defaults `retriable` to `false`).
+ *
+ * The client-visible message is a fixed, stable string; the raw driver text
+ * (which can name columns / constraints and varies by engine) is retained only
+ * as `cause` for server-side diagnostics, never interpolated into the message.
+ */
+export declare function uniqueConstraintConflict(cause: Error): ApiError;
 /** Translate a pg error code to a DistributedDatabaseErrors name. */
 export declare function translateDsqlError(e: Error): never;
 //# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,eAAO,MAAM,yBAAyB;;;;;;;CAO5B,CAAC;AAEX;;;GAGG;AAEH,qFAAqF;AACrF,eAAO,MAAM,wBAAwB,UAAU,CAAC;AAChD,8EAA8E;AAC9E,eAAO,MAAM,mBAAmB,UAAU,CAAC;AAC3C,0EAA0E;AAC1E,eAAO,MAAM,6BAA6B,OAAO,CAAC;AAElD;;;GAGG;AACH,eAAO,MAAM,qBAAqB,OAAO,CAAC;AAE1C,qEAAqE;AACrE,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,KAAK,GAAG,KAAK,CAYlD"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5C;;GAEG;AACH,eAAO,MAAM,yBAAyB;;;;;;;CAO5B,CAAC;AAEX;;;GAGG;AAEH,qFAAqF;AACrF,eAAO,MAAM,wBAAwB,UAAU,CAAC;AAChD,8EAA8E;AAC9E,eAAO,MAAM,mBAAmB,UAAU,CAAC;AAC3C,0EAA0E;AAC1E,eAAO,MAAM,6BAA6B,OAAO,CAAC;AAElD;;;GAGG;AACH,eAAO,MAAM,qBAAqB,OAAO,CAAC;AAE1C;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,KAAK,GAAG,QAAQ,CAM5D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,KAAK,GAAG,QAAQ,CAK/D;AAED,qEAAqE;AACrE,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,KAAK,GAAG,KAAK,CAmBlD"}

package/dist/errors.js

@@ -1,5 +1,6 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
+import { ApiError } from '@aws-blocks/core';
 /**
  * DSQL-specific error constants.
  */
@@ -26,14 +27,63 @@ export const PG_CONNECTION_EXCEPTION_CLASS = '08';
  * @see https://docs.aws.amazon.com/aurora-dsql/latest/userguide/working-with-transactions.html
  */
 export const TRANSACTION_ROW_LIMIT = 3000;
+/**
+ * Build the 409 ApiError for a serialization-failure (SQLSTATE 40001) OCC
+ * conflict. Maps to HTTP 409 (Conflict) so the JSON-RPC serializer emits code
+ * 409 instead of a generic 500, preserves the `SerializationFailure` name so
+ * `isBlocksError(e, DistributedDatabaseErrors.SerializationFailure)` keeps
+ * matching on both server and client, keeps the original engine error as
+ * `cause` (server-side), and flags the conflict retriable — the caller can
+ * retry the transaction (see `retryOnConflict`).
+ *
+ * The client-visible message is a fixed, stable string (the raw driver text is
+ * verbose); the original error is retained as `cause` for server-side
+ * diagnostics.
+ */
+export function serializationConflict(cause) {
+    return new ApiError('The transaction failed due to a serialization conflict', 409, {
+        name: DistributedDatabaseErrors.SerializationFailure,
+        cause,
+        retriable: true,
+    });
+}
+/**
+ * Build the 409 ApiError for a unique-constraint / duplicate-key violation
+ * (SQLSTATE 23505). Maps to HTTP 409 (Conflict) so the JSON-RPC serializer emits
+ * code 409 instead of a generic 500, preserves the `UniqueConstraintViolation`
+ * name so `isBlocksError(e, DistributedDatabaseErrors.UniqueConstraintViolation)`
+ * keeps matching on both server and client, and keeps the original engine error
+ * as `cause` (server-side).
+ *
+ * Unlike {@link serializationConflict}, this is NOT flagged retriable: a
+ * duplicate key is a deterministic constraint failure, so a blind retry of the
+ * same insert fails identically (ApiError defaults `retriable` to `false`).
+ *
+ * The client-visible message is a fixed, stable string; the raw driver text
+ * (which can name columns / constraints and varies by engine) is retained only
+ * as `cause` for server-side diagnostics, never interpolated into the message.
+ */
+export function uniqueConstraintConflict(cause) {
+    return new ApiError('The item violates a unique constraint', 409, {
+        name: DistributedDatabaseErrors.UniqueConstraintViolation,
+        cause,
+    });
+}
 /** Translate a pg error code to a DistributedDatabaseErrors name. */
 export function translateDsqlError(e) {
     const code = e.code;
     if (code === PG_SERIALIZATION_FAILURE) {
-        e.name = DistributedDatabaseErrors.SerializationFailure;
+        // An OCC / serialization-failure conflict (SQLSTATE 40001) is a Conflict,
+        // not an InternalServerError: see serializationConflict() for the full
+        // rationale (409 mapping, preserved name, retained cause, retriable flag).
+        throw serializationConflict(e);
     }
     else if (code === PG_UNIQUE_VIOLATION) {
-        e.name = DistributedDatabaseErrors.UniqueConstraintViolation;
+        // A duplicate-key / unique-constraint violation (SQLSTATE 23505) is a
+        // Conflict, not an InternalServerError: see uniqueConstraintConflict() for
+        // the full rationale (409 mapping, preserved name, retained cause, and why
+        // it is NOT retriable).
+        throw uniqueConstraintConflict(e);
     }
     else if (code && code.startsWith(PG_CONNECTION_EXCEPTION_CLASS)) {
         e.name = DistributedDatabaseErrors.ConnectionFailed;

package/dist/errors.test.js

@@ -5,19 +5,38 @@
  */
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
+import { ApiError } from '@aws-blocks/core';
 import { translateDsqlError, DistributedDatabaseErrors, PG_SERIALIZATION_FAILURE, PG_UNIQUE_VIOLATION, } from './errors.js';
+test('translateDsqlError: serialization failure (40001) → ApiError status 409, retriable', () => {
+    const err = Object.assign(new Error('conflict'), { code: PG_SERIALIZATION_FAILURE });
+    assert.throws(() => translateDsqlError(err), (e) => {
+        assert.ok(e instanceof ApiError, 'expected an ApiError');
+        assert.equal(e.status, 409);
+        assert.equal(e.name, DistributedDatabaseErrors.SerializationFailure);
+        assert.equal(e.retriable, true);
+        assert.equal(e.message, 'The transaction failed due to a serialization conflict');
+        assert.equal(e.cause.message, 'conflict');
+        return true;
+    });
+});
 test('translateDsqlError: serialization failure (40001) → SerializationFailure', () => {
     const err = Object.assign(new Error('conflict'), { code: PG_SERIALIZATION_FAILURE });
     assert.throws(() => translateDsqlError(err), (e) => {
         assert.equal(e.name, DistributedDatabaseErrors.SerializationFailure);
-        assert.equal(e.message, 'conflict');
+        assert.equal(e.message, 'The transaction failed due to a serialization conflict');
         return true;
     });
 });
-test('translateDsqlError: unique violation (23505) → UniqueConstraintViolation', () => {
-    const err = Object.assign(new Error('duplicate key'), { code: PG_UNIQUE_VIOLATION });
+test('translateDsqlError: unique violation (23505) → ApiError status 409, name preserved, not retriable', () => {
+    const err = Object.assign(new Error('duplicate key value violates unique constraint "dsql_items_pkey"'), { code: PG_UNIQUE_VIOLATION });
     assert.throws(() => translateDsqlError(err), (e) => {
+        assert.ok(e instanceof ApiError, 'expected an ApiError');
+        assert.equal(e.status, 409);
         assert.equal(e.name, DistributedDatabaseErrors.UniqueConstraintViolation);
+        assert.strictEqual(e.retriable, false, 'a duplicate-key retry fails identically → not retriable');
+        assert.equal(e.message, 'The item violates a unique constraint');
+        // Raw driver error retained server-side as `cause`, not leaked into the message.
+        assert.equal(e.cause, err);
         return true;
     });
 });

package/dist/index.aws.d.ts

@@ -23,6 +23,9 @@ export declare class DistributedDatabase extends Scope {
      *
      * DSQL uses Optimistic Concurrency Control. Commit may fail with
      * SerializationFailureException if another transaction modified the same rows.
+     * That conflict is an `ApiError` with status 409 (Conflict), flagged retriable,
+     * so it serializes to JSON-RPC code 409 (not 500); `isBlocksError(e,
+     * DistributedDatabaseErrors.SerializationFailure)` still matches by name.
      */
     transaction<T>(fn: (tx: Transaction) => Promise<T>, options?: TransactionOptions): Promise<T>;
     /** @internal */

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

@@ -1 +1 @@
-{"version":3,"file":"index.aws.d.ts","sourceRoot":"","sources":["../src/index.aws.ts"],"names":[],"mappings":"AAGA;;;GAGG;AAEH,OAAO,EAAE,KAAK,EAA0B,MAAM,kBAAkB,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAgB,KAAK,QAAQ,EAAE,KAAK,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAIxF,OAAO,KAAK,EAAE,0BAA0B,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAGjF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAGzD,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,OAAO,CAAC,KAAK,CAA6B;IAE1C,2FAA2F;IAC3F,SAAS,CAAC,GAAG,EAAE,WAAW,CAAC;gBAEf,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,0BAA0B;IAQjF,OAAO,KAAK,IAAI,GAiBf;IAED,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IACvC,QAAQ,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAC/C,OAAO,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAEvD;;;;;OAKG;IACG,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,CAAC,CAAC;IAInG,gBAAgB;IAChB,SAAS;CACV;AAED,OAAO,EAAE,GAAG,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AACnE,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACrE,OAAO,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AACxD,YAAY,EAAE,0BAA0B,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.aws.d.ts","sourceRoot":"","sources":["../src/index.aws.ts"],"names":[],"mappings":"AAGA;;;GAGG;AAEH,OAAO,EAAE,KAAK,EAA0B,MAAM,kBAAkB,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAgB,KAAK,QAAQ,EAAE,KAAK,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAIxF,OAAO,KAAK,EAAE,0BAA0B,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAGjF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAGzD,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,OAAO,CAAC,KAAK,CAA6B;IAE1C,2FAA2F;IAC3F,SAAS,CAAC,GAAG,EAAE,WAAW,CAAC;gBAEf,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,0BAA0B;IAQjF,OAAO,KAAK,IAAI,GAiBf;IAED,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IACvC,QAAQ,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAC/C,OAAO,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAEvD;;;;;;;;OAQG;IACG,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,CAAC,CAAC;IAInG,gBAAgB;IAChB,SAAS;CACV;AAED,OAAO,EAAE,GAAG,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AACnE,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACrE,OAAO,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AACxD,YAAY,EAAE,0BAA0B,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.aws.js

@@ -49,6 +49,9 @@ export class DistributedDatabase extends Scope {
      *
      * DSQL uses Optimistic Concurrency Control. Commit may fail with
      * SerializationFailureException if another transaction modified the same rows.
+     * That conflict is an `ApiError` with status 409 (Conflict), flagged retriable,
+     * so it serializes to JSON-RPC code 409 (not 500); `isBlocksError(e,
+     * DistributedDatabaseErrors.SerializationFailure)` still matches by name.
      */
     async transaction(fn, options) {
         return transactionWithRetry(this.base, fn, options);

package/dist/index.cdk.d.ts

@@ -3,10 +3,10 @@
  * Provisions Aurora DSQL cluster via CloudFormation.
  * Optionally runs migrations via a CustomResource Lambda.
  */
-import { Scope } from '@aws-blocks/core/cdk';
+import { BuildingBlockScope } from '@aws-blocks/core/cdk';
 import type { ScopeParent } from '@aws-blocks/core';
 import type { DistributedDatabaseOptions } from './types.js';
-export declare class DistributedDatabase extends Scope {
+export declare class DistributedDatabase extends BuildingBlockScope {
     constructor(scope: ScopeParent, id: string, options?: DistributedDatabaseOptions);
     /**
      * Runtime-only. This is the CDK (synth) build: it defines infrastructure and

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

@@ -1 +1 @@
-{"version":3,"file":"index.cdk.d.ts","sourceRoot":"","sources":["../src/index.cdk.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AAEH,OAAO,EAAE,KAAK,EAA0E,MAAM,sBAAsB,CAAC;AACrH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AASpD,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AAG7D,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,0BAA0B;IAwGhF;;;;;OAKG;IACH,SAAS,IAAI,KAAK;CAGnB;AAaD,OAAO,EAAE,GAAG,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AACnE,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACrE,OAAO,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AACxD,YAAY,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.cdk.d.ts","sourceRoot":"","sources":["../src/index.cdk.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AAEH,OAAO,EAAE,kBAAkB,EAA0E,MAAM,sBAAsB,CAAC;AAClI,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AASpD,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AAG7D,qBAAa,mBAAoB,SAAQ,kBAAkB;gBAC7C,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,0BAA0B;IA8GhF;;;;;OAKG;IACH,SAAS,IAAI,KAAK;CAGnB;AAaD,OAAO,EAAE,GAAG,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AACnE,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACrE,OAAO,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AACxD,YAAY,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.cdk.js

@@ -5,7 +5,7 @@
  * Provisions Aurora DSQL cluster via CloudFormation.
  * Optionally runs migrations via a CustomResource Lambda.
  */
-import { Scope, DEFAULT_NODE_RUNTIME, synthGuard, blocksNodejsBundling, registerConfig } from '@aws-blocks/core/cdk';
+import { BuildingBlockScope, DEFAULT_NODE_RUNTIME, synthGuard, blocksNodejsBundling, registerConfig } from '@aws-blocks/core/cdk';
 import * as cdk from 'aws-cdk-lib';
 import * as iam from 'aws-cdk-lib/aws-iam';
 import * as lambda from 'aws-cdk-lib/aws-lambda-nodejs';
@@ -15,9 +15,9 @@ import { createHash } from 'node:crypto';
 import { readdirSync, readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { LAMBDA_MIGRATIONS_DIR, MIGRATION_LAMBDA_TIMEOUT_MINUTES, ENV_SANITIZE, sanitizeDbRoleName } from './constants.js';
-export class DistributedDatabase extends Scope {
+export class DistributedDatabase extends BuildingBlockScope {
     constructor(scope, id, options) {
-        super(id, { parent: scope });
+        super(id, { parent: scope, vpc: { requiresEgress: true } });
         const stack = cdk.Stack.of(this);
         const envName = this.fullId.replace(ENV_SANITIZE, '_');
         const region = stack.region;
@@ -96,9 +96,15 @@ export class DistributedDatabase extends Scope {
         const provider = new cr.Provider(stack, `${this.fullId}DsqlMigrationProvider`, {
             onEventHandler: migrationFn,
         });
+        // `appRoleArn` is a property, not just a Lambda env var, because CloudFormation only
+        // re-invokes a CustomResource when its properties change. Replacing the app's IAM role
+        // changes this ARN, which is what re-runs provisionAppRole() and re-issues the DSQL
+        // `AWS IAM GRANT`. Without it, a role replacement leaves the grant on the old, deleted
+        // ARN and every query fails with 28000 (invalid_authorization_specification). The ARN is
+        // a token, so this only differs when the role is genuinely replaced — not on every deploy.
         const migrationCR = new cdk.CustomResource(stack, `${this.fullId}DsqlMigrationCR`, {
             serviceToken: provider.serviceToken,
-            properties: { migrationsHash, dbRole },
+            properties: { migrationsHash, dbRole, appRoleArn },
         });
         // Ensure migrations run after cluster is created
         migrationCR.node.addDependency(cluster);

package/dist/index.cdk.test.js

@@ -243,6 +243,32 @@ test('CDK: migration resources created when migrationsPath is provided', () => {
         rmSync(MIGRATIONS_DIR, { recursive: true, force: true });
     }
 });
+test('CDK: migration CustomResource tracks the app role ARN', () => {
+    rmSync(MIGRATIONS_DIR, { recursive: true, force: true });
+    mkdirSync(MIGRATIONS_DIR, { recursive: true });
+    writeFileSync(join(MIGRATIONS_DIR, '001_create.sql'), 'CREATE TABLE t (id TEXT PRIMARY KEY)');
+    try {
+        const template = synth((stack) => {
+            new DistributedDatabase(scope(stack), 'mydsql', { migrationsPath: MIGRATIONS_DIR });
+        });
+        const customResources = template.findResources('AWS::CloudFormation::CustomResource');
+        const cr = Object.values(customResources)[0];
+        // CloudFormation only re-invokes a CustomResource when its PROPERTIES change. The app
+        // role ARN must therefore be a property, not just a Lambda env var — otherwise replacing
+        // the app's IAM role leaves the DSQL `AWS IAM GRANT` pointing at the old, deleted ARN and
+        // every query fails with 28000 (invalid_authorization_specification).
+        assert.ok(cr.Properties?.appRoleArn, 'CustomResource should have appRoleArn property');
+        // It must be the same reference the migration Lambda receives, so the two can never drift.
+        const fns = template.findResources('AWS::Lambda::Function');
+        const migrationFnEntry = Object.entries(fns).find(([id]) => id.includes('MigrationFn'));
+        assert.ok(migrationFnEntry, 'Migration Lambda should exist');
+        const env = migrationFnEntry[1].Properties?.Environment?.Variables ?? {};
+        assert.deepStrictEqual(cr.Properties.appRoleArn, env.APP_ROLE_ARN, 'CustomResource appRoleArn should match the migration Lambda APP_ROLE_ARN env var');
+    }
+    finally {
+        rmSync(MIGRATIONS_DIR, { recursive: true, force: true });
+    }
+});
 test('CDK: migration CustomResource has migrationsHash property', () => {
     rmSync(MIGRATIONS_DIR, { recursive: true, force: true });
     mkdirSync(MIGRATIONS_DIR, { recursive: true });

package/dist/index.mock.d.ts

@@ -25,6 +25,9 @@ export declare class DistributedDatabase extends Scope {
      *
      * DSQL uses Optimistic Concurrency Control. Commit may fail with
      * SerializationFailureException if another transaction modified the same rows.
+     * That conflict is an `ApiError` with status 409 (Conflict), flagged retriable,
+     * so it serializes to JSON-RPC code 409 (not 500); `isBlocksError(e,
+     * DistributedDatabaseErrors.SerializationFailure)` still matches by name.
      */
     transaction<T>(fn: (tx: Transaction) => Promise<T>, options?: TransactionOptions): Promise<T>;
     /** Test helper: simulate OCC conflict on next commit. */

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

@@ -1 +1 @@
-{"version":3,"file":"index.mock.d.ts","sourceRoot":"","sources":["../src/index.mock.ts"],"names":[],"mappings":"AAGA;;;GAGG;AAEH,OAAO,EAAE,KAAK,EAA0B,MAAM,kBAAkB,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAgB,KAAK,QAAQ,EAAE,KAAK,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAIxF,OAAO,KAAK,EAAE,0BAA0B,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAEjF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAGzD,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,OAAO,CAAC,IAAI,CAAe;IAC3B,OAAO,CAAC,UAAU,CAAiB;IACnC,OAAO,CAAC,aAAa,CAA8B;IAEnD,2FAA2F;IAC3F,SAAS,CAAC,GAAG,EAAE,WAAW,CAAC;gBAEf,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,0BAA0B;YAelE,KAAK;IAEnB,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IACvC,QAAQ,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAC/C,OAAO,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAEvD;;;;;OAKG;IACG,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,CAAC,CAAC;IAKnG,yDAAyD;IACzD,gBAAgB,IAAI,IAAI;IAExB,gBAAgB;IAChB,SAAS;CACV;AAED,OAAO,EAAE,GAAG,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AACnE,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACrE,OAAO,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AACxD,YAAY,EAAE,0BAA0B,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.mock.d.ts","sourceRoot":"","sources":["../src/index.mock.ts"],"names":[],"mappings":"AAGA;;;GAGG;AAEH,OAAO,EAAE,KAAK,EAA0B,MAAM,kBAAkB,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAgB,KAAK,QAAQ,EAAE,KAAK,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAIxF,OAAO,KAAK,EAAE,0BAA0B,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAEjF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAGzD,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,OAAO,CAAC,IAAI,CAAe;IAC3B,OAAO,CAAC,UAAU,CAAiB;IACnC,OAAO,CAAC,aAAa,CAA8B;IAEnD,2FAA2F;IAC3F,SAAS,CAAC,GAAG,EAAE,WAAW,CAAC;gBAEf,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,0BAA0B;YAelE,KAAK;IAEnB,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IACvC,QAAQ,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAC/C,OAAO,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAEvD;;;;;;;;OAQG;IACG,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,CAAC,CAAC;IAKnG,yDAAyD;IACzD,gBAAgB,IAAI,IAAI;IAExB,gBAAgB;IAChB,SAAS;CACV;AAED,OAAO,EAAE,GAAG,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AACnE,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACrE,OAAO,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AACxD,YAAY,EAAE,0BAA0B,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.mock.js

@@ -40,6 +40,9 @@ export class DistributedDatabase extends Scope {
      *
      * DSQL uses Optimistic Concurrency Control. Commit may fail with
      * SerializationFailureException if another transaction modified the same rows.
+     * That conflict is an `ApiError` with status 409 (Conflict), flagged retriable,
+     * so it serializes to JSON-RPC code 409 (not 500); `isBlocksError(e,
+     * DistributedDatabaseErrors.SerializationFailure)` still matches by name.
      */
     async transaction(fn, options) {
         await this.ready();

package/dist/version.d.ts

@@ -1,3 +1,3 @@
 export declare const BB_NAME = "DistributedDatabase";
-export declare const BB_VERSION = "0.1.8";
+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 = 'DistributedDatabase';
-export const BB_VERSION = '0.1.8';
+export const BB_VERSION = '0.2.0';

package/package.json

@@ -1,6 +1,14 @@
 {
   "name": "@aws-blocks/bb-distributed-data",
-  "version": "0.1.8",
+  "version": "0.2.0",
+  "keywords": [
+    "aws-blocks",
+    "database",
+    "sql",
+    "dsql",
+    "serverless",
+    "aurora-dsql"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/aws-devtools-labs/aws-blocks.git",
@@ -37,9 +45,9 @@
     "test": "node --test 'dist/**/*.test.js'"
   },
   "dependencies": {
-    "@aws-blocks/core": "^0.4.0",
-    "@aws-blocks/data-common": "^0.1.4",
-    "@aws-blocks/bb-logger": "^0.1.6",
+    "@aws-blocks/core": "^0.5.0",
+    "@aws-blocks/data-common": "^0.1.5",
+    "@aws-blocks/bb-logger": "^0.2.0",
     "@aws-sdk/dsql-signer": "^3.700.0",
     "@electric-sql/pglite": "^0.2.0",
     "pg": "^8.13.0"