@aws-blocks/bb-distributed-table 0.1.3 → 0.1.4

package/dist/index.test.js

@@ -173,6 +173,178 @@ describe('DistributedTable', () => {
             ]), (err) => err.name === 'ValidationFailedException');
         });
     });
+    // ── readValidation (off | coerce | strict) ────────────────────────────────
+    // Regression for the bug bash finding #1007: get() returned raw stored values
+    // without reconciling them against the schema, so after a schema change a legacy
+    // row no longer conformed to T — an added field was absent (a schema .default()
+    // was neither applied nor persisted on write-back) and a required-no-default
+    // field made the put() half of the read-modify-write cycle throw ValidationFailed.
+    // `readValidation` defaults to 'coerce', which closes the coercible gap.
+    describe('readValidation', () => {
+        // V1: no `currency`. V2: adds `currency` with a default.
+        const orderV1 = z.object({ orderId: z.string(), total: z.number() });
+        const orderV2 = z.object({
+            orderId: z.string(),
+            total: z.number(),
+            currency: z.string().default('USD'),
+        });
+        // Fixed scope so a V1 writer and a V2 reader share the same on-disk table,
+        // simulating a schema augmentation over pre-existing (legacy) rows.
+        function legacyScope() {
+            return new Scope(`dt-legacy-${++scopeCounter}-${Date.now()}`);
+        }
+        test("default is 'coerce': get() coerces the legacy row through the current schema (fills default)", async () => {
+            const scope = legacyScope();
+            const v1 = new DistributedTable(scope, 'orders', { schema: orderV1, key: { partitionKey: 'orderId' } });
+            await v1.put({ orderId: 'o1', total: 10 });
+            // No readValidation option → defaults to 'coerce'.
+            const v2 = new DistributedTable(scope, 'orders', { schema: orderV2, key: { partitionKey: 'orderId' } });
+            const row = await v2.get({ orderId: 'o1' });
+            assert.deepEqual(row, { orderId: 'o1', total: 10, currency: 'USD' });
+        });
+        test("default 'coerce': coerced read can be written back (fixes the read-modify-write cycle)", async () => {
+            const scope = legacyScope();
+            const v1 = new DistributedTable(scope, 'orders', { schema: orderV1, key: { partitionKey: 'orderId' } });
+            await v1.put({ orderId: 'o1', total: 10 });
+            const v2 = new DistributedTable(scope, 'orders', { schema: orderV2, key: { partitionKey: 'orderId' } });
+            const row = await v2.get({ orderId: 'o1' });
+            assert.ok(row);
+            await v2.put({ ...row, total: 20 }); // must NOT throw ValidationFailed
+            assert.deepEqual(await v2.get({ orderId: 'o1' }), { orderId: 'o1', total: 20, currency: 'USD' });
+        });
+        test("'off': get() returns the raw legacy row unchanged (opt-out of coercion)", async () => {
+            const scope = legacyScope();
+            const v1 = new DistributedTable(scope, 'orders', { schema: orderV1, key: { partitionKey: 'orderId' } });
+            await v1.put({ orderId: 'o1', total: 10 });
+            const v2 = new DistributedTable(scope, 'orders', {
+                schema: orderV2, key: { partitionKey: 'orderId' }, readValidation: 'off',
+            });
+            const row = await v2.get({ orderId: 'o1' });
+            assert.deepEqual(row, { orderId: 'o1', total: 10 }); // no currency injected
+        });
+        test("'coerce': an unrecoverable row is returned RAW (never throws) so it stays readable", async () => {
+            const scope = legacyScope();
+            // Write a row that violates the strict schema (total is a string, no coercion path).
+            const loose = z.object({ orderId: z.string(), total: z.any() });
+            const strict = z.object({ orderId: z.string(), total: z.number() });
+            const w = new DistributedTable(scope, 'orders', { schema: loose, key: { partitionKey: 'orderId' } });
+            await w.put({ orderId: 'bad', total: 'not-a-number' });
+            const r = new DistributedTable(scope, 'orders', {
+                schema: strict, key: { partitionKey: 'orderId' }, readValidation: 'coerce',
+            });
+            const row = await r.get({ orderId: 'bad' }); // must NOT throw
+            assert.deepEqual(row, { orderId: 'bad', total: 'not-a-number' }); // raw fallback
+        });
+        test("'coerce' PRESERVES stored keys not in the schema (no silent data loss)", async () => {
+            const scope = legacyScope();
+            // Row stored under a schema that had an extra `legacyNote` field.
+            const wide = z.object({ orderId: z.string(), total: z.number(), legacyNote: z.string() });
+            const narrow = z.object({ orderId: z.string(), total: z.number() }); // current schema no longer declares legacyNote
+            const w = new DistributedTable(scope, 'orders', { schema: wide, key: { partitionKey: 'orderId' } });
+            await w.put({ orderId: 'o1', total: 10, legacyNote: 'keep me' });
+            // coerce (default): unknown key is preserved (coerced output merged over the raw item).
+            const coerceReader = new DistributedTable(scope, 'orders', { schema: narrow, key: { partitionKey: 'orderId' } });
+            assert.deepEqual(await coerceReader.get({ orderId: 'o1' }), { orderId: 'o1', total: 10, legacyNote: 'keep me' });
+            // off also preserves (raw passthrough) — same observable result here.
+            const offReader = new DistributedTable(scope, 'orders', {
+                schema: narrow, key: { partitionKey: 'orderId' }, readValidation: 'off',
+            });
+            assert.deepEqual(await offReader.get({ orderId: 'o1' }), { orderId: 'o1', total: 10, legacyNote: 'keep me' });
+        });
+        test("'coerce' read-modify-write does NOT drop an unknown stored key (the reviewer's scenario)", async () => {
+            const scope = legacyScope();
+            const wide = z.object({ orderId: z.string(), total: z.number(), couponCode: z.string() });
+            const narrow = z.object({ orderId: z.string(), total: z.number() }); // couponCode no longer in schema
+            const seed = new DistributedTable(scope, 'orders', { schema: wide, key: { partitionKey: 'orderId' } });
+            await seed.put({ orderId: 'A1', total: 10, couponCode: 'SAVE10' });
+            // Read, change an unrelated field, write back — couponCode must survive.
+            const t = new DistributedTable(scope, 'orders', { schema: narrow, key: { partitionKey: 'orderId' } });
+            const row = await t.get({ orderId: 'A1' });
+            assert.ok(row);
+            await t.put({ ...row, total: 50 });
+            const after = await t.get({ orderId: 'A1' });
+            assert.deepEqual(after, { orderId: 'A1', total: 50, couponCode: 'SAVE10' });
+        });
+        test("'coerce' adds a new default AND preserves an unknown key at the same time", async () => {
+            const scope = legacyScope();
+            const v1 = new DistributedTable(scope, 'orders', {
+                schema: z.object({ orderId: z.string(), total: z.number(), couponCode: z.string() }),
+                key: { partitionKey: 'orderId' },
+            });
+            await v1.put({ orderId: 'o1', total: 10, couponCode: 'X' });
+            // V2 adds currency (default) and no longer declares couponCode.
+            const v2 = new DistributedTable(scope, 'orders', {
+                schema: z.object({ orderId: z.string(), total: z.number(), currency: z.string().default('USD') }),
+                key: { partitionKey: 'orderId' },
+            });
+            assert.deepEqual(await v2.get({ orderId: 'o1' }), { orderId: 'o1', total: 10, currency: 'USD', couponCode: 'X' });
+        });
+        test("'coerce' preserves unknown keys nested inside a known object (deep)", async () => {
+            const scope = legacyScope();
+            const wide = z.object({ orderId: z.string(), meta: z.object({ a: z.number(), legacy: z.boolean() }) });
+            const narrow = z.object({ orderId: z.string(), meta: z.object({ a: z.number() }) }); // dropped meta.legacy
+            const w = new DistributedTable(scope, 'orders', { schema: wide, key: { partitionKey: 'orderId' } });
+            await w.put({ orderId: 'o1', meta: { a: 1, legacy: true } });
+            const t = new DistributedTable(scope, 'orders', { schema: narrow, key: { partitionKey: 'orderId' } });
+            assert.deepEqual(await t.get({ orderId: 'o1' }), { orderId: 'o1', meta: { a: 1, legacy: true } });
+        });
+        test("'coerce' replaces arrays wholesale — never duplicates elements", async () => {
+            const scope = legacyScope();
+            const schema = z.object({ orderId: z.string(), tags: z.array(z.string()) });
+            const w = new DistributedTable(scope, 'orders', { schema, key: { partitionKey: 'orderId' } });
+            await w.put({ orderId: 'o1', tags: ['a', 'b'] });
+            // Same schema on read: coerced tags === raw tags; merge must NOT concat them.
+            const t = new DistributedTable(scope, 'orders', { schema, key: { partitionKey: 'orderId' } });
+            assert.deepEqual(await t.get({ orderId: 'o1' }), { orderId: 'o1', tags: ['a', 'b'] });
+        });
+        test("'strict': get() throws ValidationFailed on a non-conforming stored row", async () => {
+            const scope = legacyScope();
+            const loose = z.object({ orderId: z.string(), total: z.any() });
+            const strict = z.object({ orderId: z.string(), total: z.number() });
+            const w = new DistributedTable(scope, 'orders', { schema: loose, key: { partitionKey: 'orderId' } });
+            await w.put({ orderId: 'bad', total: 'not-a-number' });
+            const r = new DistributedTable(scope, 'orders', {
+                schema: strict, key: { partitionKey: 'orderId' }, readValidation: 'strict',
+            });
+            await assert.rejects(() => r.get({ orderId: 'bad' }), (err) => err.name === 'ValidationFailedException');
+        });
+        test("'strict': a conforming row reads back fine", async () => {
+            const scope = legacyScope();
+            const v1 = new DistributedTable(scope, 'orders', { schema: orderV1, key: { partitionKey: 'orderId' } });
+            await v1.put({ orderId: 'o1', total: 10 });
+            const r = new DistributedTable(scope, 'orders', {
+                schema: orderV1, key: { partitionKey: 'orderId' }, readValidation: 'strict',
+            });
+            assert.deepEqual(await r.get({ orderId: 'o1' }), { orderId: 'o1', total: 10 });
+        });
+        test('get() still returns null for a missing item (all modes)', async () => {
+            for (const readValidation of ['off', 'coerce', 'strict']) {
+                const table = new DistributedTable(testScope(), 'orders', {
+                    schema: orderV2, key: { partitionKey: 'orderId' }, readValidation,
+                });
+                assert.equal(await table.get({ orderId: 'nope' }), null);
+            }
+        });
+        test("default 'coerce': scan() and query() coerce yielded items", async () => {
+            const scope = legacyScope();
+            const v1 = new DistributedTable(scope, 'orders', { schema: orderV1, key: { partitionKey: 'orderId' } });
+            await v1.put({ orderId: 'o1', total: 10 });
+            await v1.put({ orderId: 'o2', total: 20 });
+            const v2 = new DistributedTable(scope, 'orders', { schema: orderV2, key: { partitionKey: 'orderId' } });
+            const scanned = await collect(v2.scan());
+            assert.ok(scanned.every(o => o.currency === 'USD'));
+            const queried = await collect(v2.query({ where: { orderId: { equals: 'o1' } } }));
+            assert.deepEqual(queried, [{ orderId: 'o1', total: 10, currency: 'USD' }]);
+        });
+        test("default 'coerce': getBatch() coerces each hit and preserves null holes", async () => {
+            const scope = legacyScope();
+            const v1 = new DistributedTable(scope, 'orders', { schema: orderV1, key: { partitionKey: 'orderId' } });
+            await v1.put({ orderId: 'o1', total: 10 });
+            const v2 = new DistributedTable(scope, 'orders', { schema: orderV2, key: { partitionKey: 'orderId' } });
+            const rows = await v2.getBatch([{ orderId: 'o1' }, { orderId: 'missing' }]);
+            assert.deepEqual(rows, [{ orderId: 'o1', total: 10, currency: 'USD' }, null]);
+        });
+    });
     // ── Query: numeric sort key ─────────────────────────────────────────────
     describe('query (numeric sort key)', () => {
         function numTable() {

package/dist/parity.test.js

@@ -555,3 +555,52 @@ describe('DistributedTableErrors split the old single Validation bucket into int
         assert.strictEqual(DistributedTableErrors.Validation, undefined);
     });
 });
+describe('readValidation behaves identically on the mock and the AWS runtime', () => {
+    // V2 schema adds `currency` with a default; a legacy row lacks it.
+    const schemaV2 = z.object({ orderId: z.string(), total: z.number(), currency: z.string().default('USD') });
+    const legacyRow = { orderId: 'o1', total: 10 };
+    const coerced = { orderId: 'o1', total: 10, currency: 'USD' };
+    test("mock get() coerces a stored legacy-shaped row under the default 'coerce'", async () => {
+        // Write the legacy-shaped row directly into the store (bypassing put's
+        // write validation) to simulate a row that predates the V2 schema, then
+        // read it back through the V2 schema (readValidation defaults to 'coerce').
+        const v2 = new DistributedTable(testScope(), 'orders', {
+            schema: schemaV2, key: { partitionKey: 'orderId' },
+        });
+        v2.data.set(v2.serializeKey({ orderId: 'o1' }), legacyRow);
+        assert.deepStrictEqual(await v2.get({ orderId: 'o1' }), coerced);
+    });
+    test("AWS get() coerces the same legacy row identically under the default 'coerce'", async () => {
+        const table = awsTableWithFakeClient('ovr-aws-1', { schema: schemaV2, key: { partitionKey: 'orderId' } }, async () => ({ Item: legacyRow }));
+        assert.deepStrictEqual(await table.get({ orderId: 'o1' }), coerced);
+    });
+    test("AWS get() with readValidation 'off' returns the raw legacy row unchanged", async () => {
+        const table = awsTableWithFakeClient('ovr-aws-2', { schema: schemaV2, key: { partitionKey: 'orderId' }, readValidation: 'off' }, async () => ({ Item: legacyRow }));
+        assert.deepStrictEqual(await table.get({ orderId: 'o1' }), legacyRow);
+    });
+    test("AWS get() 'coerce' returns an uncoercible row RAW and never throws", async () => {
+        const strict = z.object({ orderId: z.string(), total: z.number() });
+        const bad = { orderId: 'x', total: 'not-a-number' };
+        const table = awsTableWithFakeClient('ovr-aws-3', { schema: strict, key: { partitionKey: 'orderId' }, readValidation: 'coerce' }, async () => ({ Item: bad }));
+        assert.deepStrictEqual(await table.get({ orderId: 'x' }), bad);
+    });
+    test("AWS get() 'strict' throws ValidationFailed on the same uncoercible row (mock parity)", async () => {
+        const strict = z.object({ orderId: z.string(), total: z.number() });
+        const bad = { orderId: 'x', total: 'not-a-number' };
+        const table = awsTableWithFakeClient('ovr-aws-4', { schema: strict, key: { partitionKey: 'orderId' }, readValidation: 'strict' }, async () => ({ Item: bad }));
+        await assert.rejects(() => table.get({ orderId: 'x' }), (err) => err.name === 'ValidationFailedException');
+    });
+    // coerce preserves unknown stored keys (adds default) — must be identical mock ↔ aws.
+    const narrow = z.object({ orderId: z.string(), total: z.number(), currency: z.string().default('USD') });
+    const legacyWithExtra = { orderId: 'o1', total: 10, couponCode: 'X' }; // couponCode not in schema
+    const preserved = { orderId: 'o1', total: 10, couponCode: 'X', currency: 'USD' };
+    test("mock 'coerce' preserves an unknown key while adding the new default", async () => {
+        const t = new DistributedTable(testScope(), 'orders', { schema: narrow, key: { partitionKey: 'orderId' } });
+        t.data.set(t.serializeKey({ orderId: 'o1' }), legacyWithExtra);
+        assert.deepStrictEqual(await t.get({ orderId: 'o1' }), preserved);
+    });
+    test("AWS 'coerce' preserves the same unknown key identically", async () => {
+        const table = awsTableWithFakeClient('ovr-aws-5', { schema: narrow, key: { partitionKey: 'orderId' } }, async () => ({ Item: legacyWithExtra }));
+        assert.deepStrictEqual(await table.get({ orderId: 'o1' }), preserved);
+    });
+});

package/dist/types.d.ts

@@ -4,6 +4,16 @@
  */
 import type { StandardSchemaV1 } from '@standard-schema/spec';
 import type { ChildLogger } from '@aws-blocks/bb-logger';
+/**
+ * Controls how reads reconcile a stored item with the schema. See
+ * {@link DistributedTableOptions.readValidation} for full semantics.
+ *
+ * - `'coerce'` (default): pass through the schema, return coerced output; on
+ *   validation failure return the raw value + warn (never throws).
+ * - `'strict'`: validate and throw `ValidationFailed` on any non-conforming item.
+ * - `'off'`: return the raw stored value with no validation.
+ */
+export type ReadValidationMode = 'off' | 'coerce' | 'strict';
 export interface TableKeyConfig<T> {
     /** Attribute name used as the partition key. Must be a field in the schema. */
     partitionKey: keyof T & string;
@@ -33,6 +43,47 @@ export interface DistributedTableOptions<T, K extends TableKeyConfig<T> = TableK
      * ```
      */
     ttl?: keyof T & string;
+    /**
+     * How reads (`get`, `getBatch`, `query`, `scan`) reconcile a stored item with
+     * the configured `schema`. Writes (`put`/`putBatch`) always validate; this
+     * governs the read side, which matters after a schema change: a row written
+     * under an older schema may no longer conform to the current type `T`.
+     *
+     * - **`'coerce'`** (default) — pass each stored item through the schema and
+     *   return its output. For transform-bearing schemas (e.g. Zod) this fills
+     *   `.default()`s and narrows types so the value satisfies `T` and the
+     *   read-modify-write cycle (`get()` → mutate → `put()`) round-trips. **Never
+     *   throws:** an item that fails validation is returned **as-is** with a
+     *   warning, keeping drifted/legacy rows readable for migration.
+     * - **`'strict'`** — validate on read and **throw** `ValidationFailed` on any
+     *   item that doesn't satisfy the schema. For tables where a mismatch should be
+     *   treated as corruption/tampering and rejected rather than absorbed. Note
+     *   this makes a single bad row fail the whole `query`/`scan`/`getBatch`.
+     * - **`'off'`** — return the raw stored value with no validation (lowest cost).
+     *   Use for hot paths, data you trust was written through this schema, or to
+     *   read items you can't yet coerce during a migration.
+     *
+     * Defaults to `'coerce'`.
+     *
+     * > **Best-effort coercion (validator-dependent).** Coercion relies on the
+     * > schema *transforming* its input. Zod fills defaults and casts; a check-only
+     * > Standard Schema validator (some Valibot/ArkType schemas) validates without
+     * > transforming, so `'coerce'` returns the value unchanged for those — it never
+     * > invents data. A required field with no default is never fabricated: under
+     * > `'coerce'` such a row is returned raw + warned; under `'strict'` it throws.
+     *
+     * @example
+     * ```typescript
+     * const orders = new DistributedTable(scope, 'orders', {
+     *   schema: orderSchemaV2,        // adds `currency: z.string().default('USD')`
+     *   key: { partitionKey: 'orderId' },
+     *   // readValidation: 'coerce' is the default
+     * });
+     * const order = await orders.get({ orderId: 'o1' }); // legacy row → currency: 'USD'
+     * await orders.put({ ...order, total: 20 });         // round-trips cleanly
+     * ```
+     */
+    readValidation?: ReadValidationMode;
     /** Wrap an existing table instead of creating one. */
     table?: ExternalTableRef;
     /** Optional logger for internal operations. When omitted, a default Logger at error level is created. */

package/dist/types.d.ts.map

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

package/dist/version.d.ts

@@ -1,3 +1,3 @@
 export declare const BB_NAME = "DistributedTable";
-export declare const BB_VERSION = "0.1.3";
+export declare const BB_VERSION = "0.1.4";
 //# 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.3';
+export const BB_VERSION = '0.1.4';

package/package.json

@@ -1,6 +1,15 @@
 {
   "name": "@aws-blocks/bb-distributed-table",
-  "version": "0.1.3",
+  "version": "0.1.4",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aws-devtools-labs/aws-blocks.git",
+    "directory": "packages/bb-distributed-table"
+  },
+  "homepage": "https://github.com/aws-devtools-labs/aws-blocks/tree/main/packages/bb-distributed-table#readme",
+  "bugs": {
+    "url": "https://github.com/aws-devtools-labs/aws-blocks/issues"
+  },
   "author": "Amazon Web Services",
   "license": "Apache-2.0",
   "type": "module",
@@ -30,11 +39,12 @@
     "test": "node --test --test-concurrency=1 dist/index.test.js dist/parity.test.js dist/index.cdk.test.js"
   },
   "dependencies": {
-    "@aws-blocks/core": "^0.1.2",
-    "@aws-blocks/bb-logger": "^0.1.2",
+    "@aws-blocks/core": "^0.1.17",
+    "@aws-blocks/bb-logger": "^0.1.3",
     "@aws-sdk/client-dynamodb": "^3.0.0",
     "@aws-sdk/lib-dynamodb": "^3.0.0",
-    "@standard-schema/spec": "^1.0.0"
+    "@standard-schema/spec": "^1.0.0",
+    "defu": "^6.1.7"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",

package/src/errors.ts

@@ -1,6 +1,33 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
+import { createDefu } from 'defu';
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { ChildLogger } from '@aws-blocks/bb-logger';
+import type { ReadValidationMode } from './types.js';
+
+/**
+ * @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,
+ * narrowed types) wins, while keys the schema stripped (e.g. attributes from an
+ * older schema version or another writer) are preserved rather than silently
+ * dropped on a read-modify-write.
+ *
+ * Arrays are treated as **opaque leaves** — the coerced array replaces the raw
+ * array wholesale. defu concatenates arrays by default, which is wrong here: the
+ * coerced array is derived from the same raw array, so concatenation would
+ * duplicate every element. This customizer overrides that one behavior; plain
+ * objects still deep-merge (so nested unknown keys survive), and defu's built-in
+ * `__proto__`/`constructor` guard is retained.
+ */
+const mergeCoercedOverRaw = createDefu((obj, key, value) => {
+	if (Array.isArray(obj[key]) || Array.isArray(value)) {
+		obj[key] = obj[key] ?? value;
+		return true;
+	}
+	return false;
+});
+
 /**
  * Typed error constants for DistributedTable. Use with `isBlocksError()` in catch blocks.
  *
@@ -143,3 +170,61 @@ export function remapItemTooLarge(err: unknown): unknown {
 	}
 	return err;
 }
+
+/**
+ * @internal Reconcile a stored item with the schema on read, per the
+ * `readValidation` mode. Shared by the mock and AWS runtime so all three modes
+ * behave identically in both. `null` (a missing item) always passes through
+ * untouched, preserving not-found semantics.
+ *
+ * - `'off'` — return the raw item, no validation.
+ * - `'coerce'` — apply the schema (fill defaults / narrow types for
+ *   transform-bearing schemas) **without dropping data**: the coerced output is
+ *   deep-merged over the raw item, so schema output wins per key while attributes
+ *   the schema doesn't declare (from an older schema version or another writer)
+ *   are preserved. Without this merge, returning the bare validator output would
+ *   strip unknown keys (Zod `.strip()` default), and a read-modify-write would
+ *   then persist the stripped item — silently deleting stored data. On validation
+ *   failure, return the **raw** item and `warn` — never throws — so drifted/legacy
+ *   rows stay readable and the "reads return data or `null`" contract holds.
+ * - `'strict'` — throw `ValidationFailed` on any item that doesn't satisfy the
+ *   schema.
+ *
+ * Schemas may validate synchronously or asynchronously; this awaits either.
+ */
+export async function applyReadValidation<T>(
+	mode: ReadValidationMode,
+	schema: StandardSchemaV1<T>,
+	item: T | null,
+	log: Pick<ChildLogger, 'warn'>,
+	context?: Record<string, unknown>,
+): Promise<T | null> {
+	if (item == null || mode === 'off') return item;
+	const result = schema['~standard'].validate(item);
+	const resolved = result instanceof Promise ? await result : result;
+	if (resolved.issues) {
+		if (mode === 'strict') {
+			throw blocksError(DistributedTableErrors.ValidationFailed, resolved.issues[0]?.message ?? 'stored item failed schema validation on read');
+		}
+		log.warn(
+			`readValidation: stored item failed schema validation, returning the raw value. ${resolved.issues[0]?.message ?? ''}`.trim(),
+			context,
+		);
+		return item;
+	}
+	// Merge coerced output over the raw item: schema wins per key, but keys the
+	// schema stripped are preserved (see mergeCoercedOverRaw). Only merge when both
+	// sides are plain objects — a schema whose output is a primitive/array (rare
+	// for a table item) is returned as-is.
+	if (isPlainObject(item) && isPlainObject(resolved.value)) {
+		return mergeCoercedOverRaw(resolved.value as Record<string, unknown>, item as Record<string, unknown>) as T;
+	}
+	return resolved.value as T;
+}
+
+/** True for a plain `{}` object (not null, array, Date, or class instance). */
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+	if (v === null || typeof v !== 'object' || Array.isArray(v)) return false;
+	const proto = Object.getPrototypeOf(v);
+	return proto === Object.prototype || proto === null;
+}

package/src/index.aws.ts

@@ -21,6 +21,7 @@ export { DistributedTableErrors } from './errors.js';
 export type {
 	TableKeyConfig,
 	DistributedTableOptions,
+	ReadValidationMode,
 	ExternalTableRef,
 	TableKey,
 	PartitionKeyCondition,
@@ -42,8 +43,9 @@ import type {
 	PartitionKeyCondition,
 	SortKeyCondition,
 	TableKey,
+	ReadValidationMode,
 } from './types.js';
-import { DistributedTableErrors, DistributedTableMessages, blocksError, normalizeSortKeyCondition, remapItemTooLarge } from './errors.js';
+import { DistributedTableErrors, DistributedTableMessages, blocksError, 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';
@@ -79,18 +81,23 @@ export class DistributedTable<
 	private schema: StandardSchemaV1<T>;
 	private keyConfig: K;
 	private indexes: Indexes;
+	private readValidation: ReadValidationMode;
 	private docClient: DynamoDBDocumentClient;
 
-	/** @internal Logger for internal operations. Defaults to error-level when not provided. */
+	/** @internal Logger for internal operations. Defaults to warn-level when not provided. */
 	protected log: ChildLogger;
 
 	constructor(scope: ScopeParent, id: string, public options: DistributedTableOptions<T, K, Indexes>) {
 		super(id, { parent: scope, bbName: BB_NAME, bbVersion: BB_VERSION });
-		this.log = options?.logger ?? new Logger(this, 'logger', { level: 'error' });
+		// Default level is 'warn' (not 'error') so the readValidation='coerce'
+		// raw-fallback warning actually surfaces — it's the only log the block
+		// emits, so this doesn't add noise. Callers can pass their own logger.
+		this.log = options?.logger ?? new Logger(this, 'logger', { level: 'warn' });
 		const tableName = options.table?.tableName ?? this.fullId.substring(0, 255);
 		this.schema = options.schema;
 		this.keyConfig = options.key;
 		this.indexes = (options.indexes ?? {}) as Indexes;
+		this.readValidation = options.readValidation ?? 'coerce';
 		const client = new DynamoDBClient({
 			customUserAgent: this.buildUserAgentChain(),
 		});
@@ -103,7 +110,7 @@ export class DistributedTable<
 			TableName: getSdkIdentifiers(this).tableName,
 			Key: this.buildKey(key),
 		}));
-		return (result.Item as T) ?? null;
+		return this.reconcileRead((result.Item as T) ?? null);
 	}
 
 	async put(item: T, options?: PutOptions<T>): Promise<void> {
@@ -178,7 +185,7 @@ export class DistributedTable<
 			const result = await this.docClient.send(command);
 
 			for (const item of result.Items ?? []) {
-				yield item as T;
+				yield (await this.reconcileRead(item as T)) as T;
 				if (options.limit && ++count >= options.limit) return;
 			}
 
@@ -198,7 +205,7 @@ export class DistributedTable<
 			}));
 
 			for (const item of result.Items ?? []) {
-				yield item as T;
+				yield (await this.reconcileRead(item as T)) as T;
 				if (options?.limit && ++count >= options.limit) return;
 			}
 
@@ -225,7 +232,9 @@ export class DistributedTable<
 				},
 			);
 		}
-		return keys.map(key => results.get(JSON.stringify(this.buildKey(key))) ?? null);
+		return Promise.all(
+			keys.map(key => this.reconcileRead(results.get(JSON.stringify(this.buildKey(key))) ?? null)),
+		);
 	}
 
 	async putBatch(items: T[]): Promise<void> {
@@ -281,6 +290,16 @@ export class DistributedTable<
 		}
 	}
 
+	/**
+	 * Reconcile a stored value with the schema per this table's `readValidation`
+	 * mode (`off` → raw, `coerce` → coerced output / raw+warn on failure, `strict`
+	 * → throw on mismatch). `null` (a missing item) passes straight through. See
+	 * {@link applyReadValidation}.
+	 */
+	private reconcileRead(item: T | null): Promise<T | null> {
+		return applyReadValidation(this.readValidation, this.schema, item, this.log, { table: this.fullId });
+	}
+
 	private buildKey(key: TableKey<T, K>): Record<string, any> {
 		const result: Record<string, any> = { [this.keyConfig.partitionKey]: (key as any)[this.keyConfig.partitionKey] };
 		if (this.keyConfig.sortKey) result[this.keyConfig.sortKey] = (key as any)[this.keyConfig.sortKey];
@@ -293,7 +312,7 @@ export class DistributedTable<
 		// and lets concurrent callers re-collide; equal jitter preserves a minimum
 		// spacing while still de-synchronising retries under shared throttling.
 		// See: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Programming.Errors.html#Programming.Errors.BatchOperations
-		const capped = Math.min(BASE_BACKOFF_MS * Math.pow(2, attempt), MAX_BACKOFF_MS);
+		const capped = Math.min(BASE_BACKOFF_MS * 2 ** attempt, MAX_BACKOFF_MS);
 		const ms = capped / 2 + Math.random() * (capped / 2);
 		return new Promise(resolve => setTimeout(resolve, ms));
 	}

package/src/index.cdk.ts

@@ -15,7 +15,7 @@ import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
 
 export { DistributedTableErrors } from './errors.js';
-export type { DistributedTableOptions, TableKeyConfig, TableKey, PutOptions, DeleteOptions, QueryOptions, ScanOptions, ExternalTableRef } from './types.js';
+export type { DistributedTableOptions, ReadValidationMode, TableKeyConfig, TableKey, PutOptions, DeleteOptions, QueryOptions, ScanOptions, ExternalTableRef } from './types.js';
 
 export class DistributedTable<T = any> extends Scope {
 	private table: ITable;