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

package/DESIGN.md

@@ -81,6 +81,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.

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":"AAYA,OAAO,EAAE,KAAK,EAAoC,MAAM,sBAAsB,CAAC;AAC/E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAItE,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AACrD,YAAY,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,cAAc,EAAE,QAAQ,EAAE,UAAU,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEnM,qBAAa,gBAAgB,CAAC,CAAC,GAAG,GAAG,CAAE,SAAQ,KAAK;IA2BA,OAAO,EAAE,GAAG;IA1B/D,OAAO,CAAC,KAAK,CAAS;IAEtB;;;;;;OAMG;IACH,MAAM,CAAC,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB;IAIxD;;;;;;;;OAQG;IACH,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB;gBAIxC,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,EAAS,OAAO,EAAE,GAAG;IAqO/D,GAAG,CAAC,GAAG,KAAK,EAAE,OAAO,EAAE,GAAG,KAAK;IAC/B,GAAG,CAAC,GAAG,KAAK,EAAE,OAAO,EAAE,GAAG,KAAK;IAC/B,MAAM,CAAC,GAAG,KAAK,EAAE,OAAO,EAAE,GAAG,KAAK;IAClC,KAAK,CAAC,GAAG,KAAK,EAAE,OAAO,EAAE,GAAG,KAAK;IACjC,IAAI,CAAC,GAAG,KAAK,EAAE,OAAO,EAAE,GAAG,KAAK;IAChC,QAAQ,CAAC,GAAG,KAAK,EAAE,OAAO,EAAE,GAAG,KAAK;IACpC,QAAQ,CAAC,GAAG,KAAK,EAAE,OAAO,EAAE,GAAG,KAAK;IACpC,WAAW,CAAC,GAAG,KAAK,EAAE,OAAO,EAAE,GAAG,KAAK;CACvC"}

package/dist/index.cdk.js

@@ -4,6 +4,7 @@ import { Table, AttributeType, BillingMode, TableEncryption } from 'aws-cdk-lib/
 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';
@@ -207,7 +208,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 +250,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

@@ -212,7 +212,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;
@@ -295,6 +302,28 @@ export class DistributedTable extends Scope {
             }
         }
     }
+    /**
+     * 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

@@ -724,4 +724,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.1.7";
 //# 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.1.7';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aws-blocks/bb-distributed-table",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/aws-devtools-labs/aws-blocks.git",
@@ -39,8 +39,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.4.0",
+    "@aws-blocks/bb-logger": "^0.1.6",
     "@aws-sdk/client-dynamodb": "^3.0.0",
     "@aws-sdk/lib-dynamodb": "^3.0.0",
     "@standard-schema/spec": "^1.0.0",

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

@@ -6,6 +6,7 @@ import { Table, type ITable, AttributeType, BillingMode, TableEncryption } from
 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';
@@ -239,7 +240,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 +294,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 +303,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 +322,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

@@ -266,7 +266,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;
 			});
 		}
 
@@ -359,6 +366,27 @@ export class DistributedTable<
 		}
 	}
 
+	/**
+	 * 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

@@ -859,4 +859,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.1.7';