@atscript/moost-db 0.1.152 → 0.1.153

package/dist/index.cjs

@@ -85,6 +85,9 @@ const dbErrorCodeToStatus = {
 	CAS_MISMATCH: 409,
 	TX_WAIT_TIMEOUT: 503,
 	SPACE_CLOSED: 503,
+	DEADLOCK: 503,
+	LOCK_TIMEOUT: 503,
+	SERIALIZATION_FAILURE: 503,
 	BUCKET_TZ_UNAVAILABLE: 501
 };
 function transformValidationError(error, reply) {
@@ -168,6 +171,15 @@ var SortControlDto = class {
 		(0, _atscript_typescript_utils.throwFeatureDisabled)("JSON Schema", "jsonSchema", "emit.jsonSchema");
 	}
 };
+var NullsControlDto = class {
+	static __is_atscript_annotated_type = true;
+	static type = {};
+	static metadata = /* @__PURE__ */ new Map();
+	static id = "NullsControlDto";
+	static toJsonSchema() {
+		(0, _atscript_typescript_utils.throwFeatureDisabled)("JSON Schema", "jsonSchema", "emit.jsonSchema");
+	}
+};
 var SelectControlDto = class {
 	static __is_atscript_annotated_type = true;
 	static type = {};
@@ -177,7 +189,7 @@ var SelectControlDto = class {
 		(0, _atscript_typescript_utils.throwFeatureDisabled)("JSON Schema", "jsonSchema", "emit.jsonSchema");
 	}
 };
-(0, _atscript_typescript_utils.defineAnnotatedType)("object", QueryControlsDto).prop("$skip", (0, _atscript_typescript_utils.defineAnnotatedType)().designType("number").tags("positive", "int", "number").annotate("expect.int", true).annotate("expect.min", { minValue: 0 }).optional().$type).prop("$limit", (0, _atscript_typescript_utils.defineAnnotatedType)().designType("number").tags("positive", "int", "number").annotate("expect.int", true).annotate("expect.min", { minValue: 0 }).optional().$type).prop("$count", (0, _atscript_typescript_utils.defineAnnotatedType)().designType("boolean").tags("boolean").optional().$type).prop("$sort", (0, _atscript_typescript_utils.defineAnnotatedType)().refTo(SortControlDto).optional().$type).prop("$select", (0, _atscript_typescript_utils.defineAnnotatedType)("union").item((0, _atscript_typescript_utils.defineAnnotatedType)().refTo(SelectControlDto).$type).item((0, _atscript_typescript_utils.defineAnnotatedType)("array").of((0, _atscript_typescript_utils.defineAnnotatedType)().designType("string").tags("string").$type).$type).optional().$type).prop("$search", (0, _atscript_typescript_utils.defineAnnotatedType)().designType("string").tags("string").optional().$type).prop("$index", (0, _atscript_typescript_utils.defineAnnotatedType)().designType("string").tags("string").optional().$type).prop("$fuzzy", (0, _atscript_typescript_utils.defineAnnotatedType)().designType("string").tags("string").optional().$type).prop("$vector", (0, _atscript_typescript_utils.defineAnnotatedType)().designType("string").tags("string").optional().$type).prop("$threshold", (0, _atscript_typescript_utils.defineAnnotatedType)().designType("string").tags("string").optional().$type).prop("$with", (0, _atscript_typescript_utils.defineAnnotatedType)("array").of((0, _atscript_typescript_utils.defineAnnotatedType)().refTo(WithRelationDto).$type).optional().$type).prop("$actions", (0, _atscript_typescript_utils.defineAnnotatedType)().designType("boolean").tags("boolean").optional().$type);
+(0, _atscript_typescript_utils.defineAnnotatedType)("object", QueryControlsDto).prop("$skip", (0, _atscript_typescript_utils.defineAnnotatedType)().designType("number").tags("positive", "int", "number").annotate("expect.int", true).annotate("expect.min", { minValue: 0 }).optional().$type).prop("$limit", (0, _atscript_typescript_utils.defineAnnotatedType)().designType("number").tags("positive", "int", "number").annotate("expect.int", true).annotate("expect.min", { minValue: 0 }).optional().$type).prop("$count", (0, _atscript_typescript_utils.defineAnnotatedType)().designType("boolean").tags("boolean").optional().$type).prop("$sort", (0, _atscript_typescript_utils.defineAnnotatedType)().refTo(SortControlDto).optional().$type).prop("$nulls", (0, _atscript_typescript_utils.defineAnnotatedType)().refTo(NullsControlDto).optional().$type).prop("$select", (0, _atscript_typescript_utils.defineAnnotatedType)("union").item((0, _atscript_typescript_utils.defineAnnotatedType)().refTo(SelectControlDto).$type).item((0, _atscript_typescript_utils.defineAnnotatedType)("array").of((0, _atscript_typescript_utils.defineAnnotatedType)().designType("string").tags("string").$type).$type).optional().$type).prop("$search", (0, _atscript_typescript_utils.defineAnnotatedType)().designType("string").tags("string").optional().$type).prop("$index", (0, _atscript_typescript_utils.defineAnnotatedType)().designType("string").tags("string").optional().$type).prop("$fuzzy", (0, _atscript_typescript_utils.defineAnnotatedType)().designType("string").tags("string").optional().$type).prop("$vector", (0, _atscript_typescript_utils.defineAnnotatedType)().designType("string").tags("string").optional().$type).prop("$threshold", (0, _atscript_typescript_utils.defineAnnotatedType)().designType("string").tags("string").optional().$type).prop("$with", (0, _atscript_typescript_utils.defineAnnotatedType)("array").of((0, _atscript_typescript_utils.defineAnnotatedType)().refTo(WithRelationDto).$type).optional().$type).prop("$actions", (0, _atscript_typescript_utils.defineAnnotatedType)().designType("boolean").tags("boolean").optional().$type);
 (0, _atscript_typescript_utils.defineAnnotatedType)("object", PagesControlsDto).prop("$page", (0, _atscript_typescript_utils.defineAnnotatedType)().designType("string").tags("string").annotate("expect.pattern", {
 	pattern: "^\\d+$",
 	flags: "u",
@@ -186,7 +198,7 @@ var SelectControlDto = class {
 	pattern: "^\\d+$",
 	flags: "u",
 	message: "Expected positive number"
-}, true).optional().$type).prop("$sort", (0, _atscript_typescript_utils.defineAnnotatedType)().refTo(SortControlDto).optional().$type).prop("$select", (0, _atscript_typescript_utils.defineAnnotatedType)("union").item((0, _atscript_typescript_utils.defineAnnotatedType)().refTo(SelectControlDto).$type).item((0, _atscript_typescript_utils.defineAnnotatedType)("array").of((0, _atscript_typescript_utils.defineAnnotatedType)().designType("string").tags("string").$type).$type).optional().$type).prop("$search", (0, _atscript_typescript_utils.defineAnnotatedType)().designType("string").tags("string").optional().$type).prop("$index", (0, _atscript_typescript_utils.defineAnnotatedType)().designType("string").tags("string").optional().$type).prop("$fuzzy", (0, _atscript_typescript_utils.defineAnnotatedType)().designType("string").tags("string").optional().$type).prop("$vector", (0, _atscript_typescript_utils.defineAnnotatedType)().designType("string").tags("string").optional().$type).prop("$threshold", (0, _atscript_typescript_utils.defineAnnotatedType)().designType("string").tags("string").optional().$type).prop("$with", (0, _atscript_typescript_utils.defineAnnotatedType)("array").of((0, _atscript_typescript_utils.defineAnnotatedType)().refTo(WithRelationDto).$type).optional().$type).prop("$actions", (0, _atscript_typescript_utils.defineAnnotatedType)().designType("boolean").tags("boolean").optional().$type);
+}, true).optional().$type).prop("$sort", (0, _atscript_typescript_utils.defineAnnotatedType)().refTo(SortControlDto).optional().$type).prop("$nulls", (0, _atscript_typescript_utils.defineAnnotatedType)().refTo(NullsControlDto).optional().$type).prop("$select", (0, _atscript_typescript_utils.defineAnnotatedType)("union").item((0, _atscript_typescript_utils.defineAnnotatedType)().refTo(SelectControlDto).$type).item((0, _atscript_typescript_utils.defineAnnotatedType)("array").of((0, _atscript_typescript_utils.defineAnnotatedType)().designType("string").tags("string").$type).$type).optional().$type).prop("$search", (0, _atscript_typescript_utils.defineAnnotatedType)().designType("string").tags("string").optional().$type).prop("$index", (0, _atscript_typescript_utils.defineAnnotatedType)().designType("string").tags("string").optional().$type).prop("$fuzzy", (0, _atscript_typescript_utils.defineAnnotatedType)().designType("string").tags("string").optional().$type).prop("$vector", (0, _atscript_typescript_utils.defineAnnotatedType)().designType("string").tags("string").optional().$type).prop("$threshold", (0, _atscript_typescript_utils.defineAnnotatedType)().designType("string").tags("string").optional().$type).prop("$with", (0, _atscript_typescript_utils.defineAnnotatedType)("array").of((0, _atscript_typescript_utils.defineAnnotatedType)().refTo(WithRelationDto).$type).optional().$type).prop("$actions", (0, _atscript_typescript_utils.defineAnnotatedType)().designType("boolean").tags("boolean").optional().$type);
 (0, _atscript_typescript_utils.defineAnnotatedType)("object", GetOneControlsDto).prop("$select", (0, _atscript_typescript_utils.defineAnnotatedType)("union").item((0, _atscript_typescript_utils.defineAnnotatedType)().refTo(SelectControlDto).$type).item((0, _atscript_typescript_utils.defineAnnotatedType)("array").of((0, _atscript_typescript_utils.defineAnnotatedType)().designType("string").tags("string").$type).$type).optional().$type).prop("$with", (0, _atscript_typescript_utils.defineAnnotatedType)("array").of((0, _atscript_typescript_utils.defineAnnotatedType)().refTo(WithRelationDto).$type).optional().$type).prop("$actions", (0, _atscript_typescript_utils.defineAnnotatedType)().designType("boolean").tags("boolean").optional().$type);
 (0, _atscript_typescript_utils.defineAnnotatedType)("object", GeoControlsDto).prop("$center", (0, _atscript_typescript_utils.defineAnnotatedType)("union").item((0, _atscript_typescript_utils.defineAnnotatedType)().designType("string").tags("string").$type).item((0, _atscript_typescript_utils.defineAnnotatedType)("array").of((0, _atscript_typescript_utils.defineAnnotatedType)().designType("string").tags("string").$type).$type).item((0, _atscript_typescript_utils.defineAnnotatedType)("array").of((0, _atscript_typescript_utils.defineAnnotatedType)().designType("number").tags("number").$type).$type).optional().$type).prop("$maxDistance", (0, _atscript_typescript_utils.defineAnnotatedType)().designType("number").tags("number").optional().$type).prop("$minDistance", (0, _atscript_typescript_utils.defineAnnotatedType)().designType("number").tags("number").optional().$type).prop("$index", (0, _atscript_typescript_utils.defineAnnotatedType)().designType("string").tags("string").optional().$type).prop("$select", (0, _atscript_typescript_utils.defineAnnotatedType)("union").item((0, _atscript_typescript_utils.defineAnnotatedType)().refTo(SelectControlDto).$type).item((0, _atscript_typescript_utils.defineAnnotatedType)("array").of((0, _atscript_typescript_utils.defineAnnotatedType)().designType("string").tags("string").$type).$type).optional().$type).prop("$skip", (0, _atscript_typescript_utils.defineAnnotatedType)().designType("number").tags("positive", "int", "number").annotate("expect.int", true).annotate("expect.min", { minValue: 0 }).optional().$type).prop("$limit", (0, _atscript_typescript_utils.defineAnnotatedType)().designType("number").tags("positive", "int", "number").annotate("expect.int", true).annotate("expect.min", { minValue: 0 }).optional().$type).prop("$page", (0, _atscript_typescript_utils.defineAnnotatedType)().designType("string").tags("string").annotate("expect.pattern", {
 	pattern: "^\\d+$",
@@ -198,9 +210,10 @@ var SelectControlDto = class {
 	message: "Expected positive number"
 }, true).optional().$type).prop("$with", (0, _atscript_typescript_utils.defineAnnotatedType)("array").of((0, _atscript_typescript_utils.defineAnnotatedType)().refTo(WithRelationDto).$type).optional().$type).prop("$actions", (0, _atscript_typescript_utils.defineAnnotatedType)().designType("boolean").tags("boolean").optional().$type);
 (0, _atscript_typescript_utils.defineAnnotatedType)("object", WithRelationDto).prop("name", (0, _atscript_typescript_utils.defineAnnotatedType)().designType("string").tags("string").$type).prop("filter", (0, _atscript_typescript_utils.defineAnnotatedType)().refTo(WithFilterDto).optional().$type).prop("controls", (0, _atscript_typescript_utils.defineAnnotatedType)().refTo(WithRelationControlsDto).optional().$type).prop("insights", (0, _atscript_typescript_utils.defineAnnotatedType)().refTo(WithFilterDto).optional().$type);
-(0, _atscript_typescript_utils.defineAnnotatedType)("object", WithRelationControlsDto).prop("$skip", (0, _atscript_typescript_utils.defineAnnotatedType)().designType("number").tags("positive", "int", "number").annotate("expect.int", true).annotate("expect.min", { minValue: 0 }).optional().$type).prop("$limit", (0, _atscript_typescript_utils.defineAnnotatedType)().designType("number").tags("positive", "int", "number").annotate("expect.int", true).annotate("expect.min", { minValue: 0 }).optional().$type).prop("$sort", (0, _atscript_typescript_utils.defineAnnotatedType)().refTo(SortControlDto).optional().$type).prop("$select", (0, _atscript_typescript_utils.defineAnnotatedType)("union").item((0, _atscript_typescript_utils.defineAnnotatedType)().refTo(SelectControlDto).$type).item((0, _atscript_typescript_utils.defineAnnotatedType)("array").of((0, _atscript_typescript_utils.defineAnnotatedType)().designType("string").tags("string").$type).$type).optional().$type).prop("$with", (0, _atscript_typescript_utils.defineAnnotatedType)("array").of((0, _atscript_typescript_utils.defineAnnotatedType)().refTo(WithRelationDto).$type).optional().$type);
+(0, _atscript_typescript_utils.defineAnnotatedType)("object", WithRelationControlsDto).prop("$skip", (0, _atscript_typescript_utils.defineAnnotatedType)().designType("number").tags("positive", "int", "number").annotate("expect.int", true).annotate("expect.min", { minValue: 0 }).optional().$type).prop("$limit", (0, _atscript_typescript_utils.defineAnnotatedType)().designType("number").tags("positive", "int", "number").annotate("expect.int", true).annotate("expect.min", { minValue: 0 }).optional().$type).prop("$sort", (0, _atscript_typescript_utils.defineAnnotatedType)().refTo(SortControlDto).optional().$type).prop("$nulls", (0, _atscript_typescript_utils.defineAnnotatedType)().refTo(NullsControlDto).optional().$type).prop("$select", (0, _atscript_typescript_utils.defineAnnotatedType)("union").item((0, _atscript_typescript_utils.defineAnnotatedType)().refTo(SelectControlDto).$type).item((0, _atscript_typescript_utils.defineAnnotatedType)("array").of((0, _atscript_typescript_utils.defineAnnotatedType)().designType("string").tags("string").$type).$type).optional().$type).prop("$with", (0, _atscript_typescript_utils.defineAnnotatedType)("array").of((0, _atscript_typescript_utils.defineAnnotatedType)().refTo(WithRelationDto).$type).optional().$type);
 (0, _atscript_typescript_utils.defineAnnotatedType)("object", WithFilterDto).propPattern(/./, (0, _atscript_typescript_utils.defineAnnotatedType)("union").item((0, _atscript_typescript_utils.defineAnnotatedType)().designType("string").tags("string").$type).item((0, _atscript_typescript_utils.defineAnnotatedType)().designType("number").tags("number").$type).item((0, _atscript_typescript_utils.defineAnnotatedType)().designType("boolean").tags("boolean").$type).item((0, _atscript_typescript_utils.defineAnnotatedType)().designType("null").tags("null").$type).item((0, _atscript_typescript_utils.defineAnnotatedType)().refTo(WithFilterDto).$type).item((0, _atscript_typescript_utils.defineAnnotatedType)("array").of((0, _atscript_typescript_utils.defineAnnotatedType)().refTo(WithFilterDto).$type).$type).$type);
 (0, _atscript_typescript_utils.defineAnnotatedType)("object", SortControlDto).propPattern(/./, (0, _atscript_typescript_utils.defineAnnotatedType)("union").item((0, _atscript_typescript_utils.defineAnnotatedType)().designType("number").value(1).$type).item((0, _atscript_typescript_utils.defineAnnotatedType)().designType("number").value(-1).$type).$type);
+(0, _atscript_typescript_utils.defineAnnotatedType)("object", NullsControlDto).propPattern(/./, (0, _atscript_typescript_utils.defineAnnotatedType)("union").item((0, _atscript_typescript_utils.defineAnnotatedType)().designType("string").value("first").$type).item((0, _atscript_typescript_utils.defineAnnotatedType)().designType("string").value("last").$type).$type);
 (0, _atscript_typescript_utils.defineAnnotatedType)("object", SelectControlDto).propPattern(/./, (0, _atscript_typescript_utils.defineAnnotatedType)("union").item((0, _atscript_typescript_utils.defineAnnotatedType)().designType("number").value(1).$type).item((0, _atscript_typescript_utils.defineAnnotatedType)().designType("number").value(0).$type).$type);
 //#endregion
 //#region src/mate.ts
@@ -2861,7 +2874,7 @@ let AsReadableController = _AsReadableController = class AsReadableController {
 	* keys the shared db validator plugin reads in db-client (`db.json`,
 	* `db.patch.strategy`, `db.default*`, `db.column.version`,
 	* `db.column.derived`) and the client-facing `db.http.path` /
-	* `db.writeOnly`; strips every other `db.*` (table, column, index, etc.).
+	* `db.writeOnly` / `db.sort.nulls`; strips every other `db.*` (table, column, index, etc.).
 	* Override in subclass to customise — keep the validator keys, or client
 	* preflight diverges from the server.
 	*/
@@ -2873,7 +2886,7 @@ let AsReadableController = _AsReadableController = class AsReadableController {
 					key,
 					value
 				};
-				if (key === "db.json" || key === "db.patch.strategy" || key.startsWith("db.default") || key === "db.http.path" || key === "db.writeOnly" || key === "db.column.version" || key === "db.column.derived") return {
+				if (key === "db.json" || key === "db.patch.strategy" || key.startsWith("db.default") || key === "db.http.path" || key === "db.writeOnly" || key === "db.column.version" || key === "db.column.derived" || key === "db.sort.nulls") return {
 					key,
 					value
 				};
@@ -3499,7 +3512,7 @@ function validateMultiId(body, source, maxIds = Infinity) {
 }
 function collectIdErrors(value, source, opts) {
 	const pathPrefix = opts.path ?? "";
-	if (!isPlainObject$2(value)) return [{
+	if (!isPlainObject$3(value)) return [{
 		path: pathPrefix,
 		message: "Expected JSON object for row identifier",
 		details: []
@@ -3550,7 +3563,7 @@ function describe(value) {
 	if (Array.isArray(value)) return "array";
 	return typeof value;
 }
-function isPlainObject$2(value) {
+function isPlainObject$3(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 //#endregion
@@ -5338,7 +5351,10 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 				if (sealed.size === 0) return void 0;
 				const refs = (0, _atscript_db.collectQueryPaths)({
 					filter: rel.filter,
-					controls: { $sort: nested.$sort ?? rel.$sort }
+					controls: {
+						$sort: nested.$sort ?? rel.$sort,
+						$nulls: nested.$nulls ?? rel.$nulls
+					}
 				});
 				const filtered = refs.filter.find((ref) => (0, _atscript_db.selfOrAncestor)(ref.path, sealed) !== void 0)?.path;
 				if (filtered !== void 0) return writeOnlyError(`${path}.${filtered}`, "filter");
@@ -7053,7 +7069,29 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 		})).data;
 	}
 	/**
-	* **GET /pages** — returns paginated records with metadata.
+	* The `/pages` read without a `$sort` (since 0.1.153): ordered by the
+	* primary key, ascending, so consecutive pages neither overlap nor skip
+	* rows. A request with `$sort` keeps it (the core appends the primary key
+	* as the tie-breaker); a source without a primary key (a view without
+	* `@meta.id`) stays unordered. Only the plain read: text / vector search
+	* keep their relevance order.
+	*/
+	_pagesOrder(q) {
+		const controls = q.controls;
+		const sort = controls?.$sort;
+		const pk = this.readable.primaryKeys;
+		if (sort && Object.keys(sort).length > 0 || pk.length === 0) return q;
+		return {
+			...q,
+			controls: {
+				...controls,
+				$sort: Object.fromEntries(pk.map((f) => [f, 1]))
+			}
+		};
+	}
+	/**
+	* **GET /pages** — returns paginated records with metadata. Without a
+	* `$sort` the rows come in primary-key order (since 0.1.153).
 	*/
 	async pages(url) {
 		const { parsed, controls } = await this.parseRequest("pages", url);
@@ -7080,7 +7118,7 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 			switch (strategy.kind) {
 				case "vector": return strategy.vectorField ? this.readable.vectorSearchWithCount(strategy.vectorField, strategy.vector, q) : this.readable.vectorSearchWithCount(strategy.vector, q);
 				case "search": return this.readable.searchWithCount(strategy.term, q, strategy.index);
-				case "plain": return this.readable.findManyWithCount(q);
+				case "plain": return this.readable.findManyWithCount(this._pagesOrder(q));
 			}
 		});
 		return {
@@ -7564,7 +7602,8 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 			versionColumn: this.readable.versionColumn,
 			...capabilities.bucketUnits.length > 0 && { bucketUnits: [...capabilities.bucketUnits] },
 			aggregateFns: [...capabilities.aggregateFns],
-			aggregateExpressions: capabilities.aggregateExpressions
+			aggregateExpressions: capabilities.aggregateExpressions,
+			...typeof this.readable.supportsNullsPlacement === "function" && this.readable.supportsNullsPlacement() && { nullsPlacement: true }
 		};
 	}
 	buildCrud() {
@@ -8164,7 +8203,22 @@ let AsValueHelpController = class AsValueHelpController extends AsReadableContro
 		return (await this.query(await this._scopedQuery(parsed.filter, controls))).data;
 	}
 	/**
-	* **GET /pages** — paginated row window plus total count.
+	* `/pages` controls without a `$sort` (since 0.1.153): ordered by the
+	* primary key, ascending, so consecutive pages neither overlap nor skip
+	* rows — like the DB controllers' `/pages`. A request with `$sort` or
+	* `$search` keeps its order; a source without a primary key stays as is.
+	*/
+	_pagesOrder(controls) {
+		const sort = controls.$sort;
+		if ((Array.isArray(sort) ? sort.length > 0 : (0, _atscript_db.isPlainObject)(sort) ? !(0, _atscript_db.isEmptyObject)(sort) : !!sort) || controls.$search || !this.primaryKey) return controls;
+		return {
+			...controls,
+			$sort: { [this.primaryKey]: 1 }
+		};
+	}
+	/**
+	* **GET /pages** — paginated row window plus total count. Without a
+	* `$sort` the rows come in primary-key order (since 0.1.153).
 	*/
 	async runPages(url) {
 		const { parsed, controls } = await this.parseRequest("pages", url);
@@ -8173,11 +8227,11 @@ let AsValueHelpController = class AsValueHelpController extends AsReadableContro
 		const page = Math.max(Number(controls.$page || 1), 1);
 		const size = Math.max(Number(controls.$size || 10), 1);
 		const skip = (page - 1) * size;
-		const result = await this.query(await this._scopedQuery(parsed.filter, {
+		const result = await this.query(await this._scopedQuery(parsed.filter, this._pagesOrder({
 			...controls,
 			$skip: skip,
 			$limit: size
-		}));
+		})));
 		return {
 			data: result.data,
 			page,
@@ -8317,7 +8371,7 @@ let AsJsonValueHelpController = class AsJsonValueHelpController extends AsValueH
 			rows = rows.filter((row) => predicate(row));
 		}
 		const sort = this.normalizeSort(controls.controls.$sort);
-		if (sort) rows = (0, _atscript_db_memory.sortRows)(rows, sort);
+		if (sort) rows = (0, _atscript_db_memory.sortRows)(rows, sort, void 0, void 0, controls.controls.$nulls);
 		const total = rows.length;
 		const skip = Math.max(0, Number(controls.controls.$skip ?? 0));
 		const limit = Math.max(0, Number(controls.controls.$limit ?? total - skip));

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import { a as resolveDbSpace, i as provideDbSpace, n as clearDbSpaces, r as closeDbSpaces, t as DEFAULT_DB_SPACE } from "./db-space-registry-fXB8LnGe.cjs";
 import { TAtscriptAnnotatedType, TAtscriptDataType, TSerializeOptions, TSerializedAnnotatedType, TValidatorOptions, Validator } from "@atscript/typescript/utils";
-import { AggregateFn, AtscriptDbReadable, AtscriptDbTable, BucketUnit, FilterExpr, FlatOf, TCrudOp, TCrudOp as TCrudOp$1, TCrudPermissions, TCrudPermissions as TCrudPermissions$1, TDbActionInfo, TDbActionInfo as TDbActionInfo$1, TDbActionIntent, TDbActionIntent as TDbActionIntent$1, TDbActionLevel, TDbActionLevel as TDbActionLevel$1, TDbActionProcessor, TDbActionTargetSummary, TDbActionTargetSummary as TDbActionTargetSummary$1, TDbAvailableActions, TDbAvailableActions as TDbAvailableActions$1, TDbFieldMeta, TDbRemoveGuardContext, TDbRemoveGuardContext as TDbRemoveGuardContext$1, TDbWriteAction, TDbWriteAction as TDbWriteAction$1, TDbWriteCheckContext, TDbWriteCheckContext as TDbWriteCheckContext$1, TDbWriteGuardContext, TDbWriteGuardContext as TDbWriteGuardContext$1, TFilterPredicate, TIdResolveOptions, TIdentification, TMetaResponse, TQueryPathOp, TQueryPathOp as TQueryPathOp$1, TQueryPathRefs, TQueryPathSource, Uniquery, UniqueryControls, collectQueryPaths } from "@atscript/db";
+import { AggregateFn, AtscriptDbReadable, AtscriptDbTable, BucketUnit, FilterExpr, FlatOf, NullsPlacement, TCrudOp, TCrudOp as TCrudOp$1, TCrudPermissions, TCrudPermissions as TCrudPermissions$1, TDbActionInfo, TDbActionInfo as TDbActionInfo$1, TDbActionIntent, TDbActionIntent as TDbActionIntent$1, TDbActionLevel, TDbActionLevel as TDbActionLevel$1, TDbActionProcessor, TDbActionTargetSummary, TDbActionTargetSummary as TDbActionTargetSummary$1, TDbAvailableActions, TDbAvailableActions as TDbAvailableActions$1, TDbFieldMeta, TDbRemoveGuardContext, TDbRemoveGuardContext as TDbRemoveGuardContext$1, TDbWriteAction, TDbWriteAction as TDbWriteAction$1, TDbWriteCheckContext, TDbWriteCheckContext as TDbWriteCheckContext$1, TDbWriteGuardContext, TDbWriteGuardContext as TDbWriteGuardContext$1, TFilterPredicate, TIdResolveOptions, TIdentification, TMetaResponse, TQueryPathOp, TQueryPathOp as TQueryPathOp$1, TQueryPathRefs, TQueryPathSource, Uniquery, UniqueryControls, collectQueryPaths } from "@atscript/db";
 import { HttpError } from "@moostjs/event-http";
 import { Mate, Moost, TConsoleBase, TMateParamMeta, TMoostMetadata } from "moost";
 import { parseUrl } from "@uniqu/url";
@@ -243,7 +243,7 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
    * keys the shared db validator plugin reads in db-client (`db.json`,
    * `db.patch.strategy`, `db.default*`, `db.column.version`,
    * `db.column.derived`) and the client-facing `db.http.path` /
-   * `db.writeOnly`; strips every other `db.*` (table, column, index, etc.).
+   * `db.writeOnly` / `db.sort.nulls`; strips every other `db.*` (table, column, index, etc.).
    * Override in subclass to customise — keep the validator keys, or client
    * preflight diverges from the server.
    */
@@ -2076,7 +2076,17 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    */
   query(url: string): Promise<DataType[] | number | HttpError>;
   /**
-   * **GET /pages** — returns paginated records with metadata.
+   * The `/pages` read without a `$sort` (since 0.1.153): ordered by the
+   * primary key, ascending, so consecutive pages neither overlap nor skip
+   * rows. A request with `$sort` keeps it (the core appends the primary key
+   * as the tie-breaker); a source without a primary key (a view without
+   * `@meta.id`) stays unordered. Only the plain read: text / vector search
+   * keep their relevance order.
+   */
+  private _pagesOrder;
+  /**
+   * **GET /pages** — returns paginated records with metadata. Without a
+   * `$sort` the rows come in primary-key order (since 0.1.153).
    */
   pages(url: string): Promise<{
     data: DataType[];
@@ -2464,7 +2474,8 @@ interface ValueHelpQuery<T> {
     $limit?: number;
     $search?: string;
     $select?: (keyof T | string)[];
-    $sort?: unknown;
+    $sort?: unknown; /** NULL placement per `$sort` key (URL `$sort=-name:last`; since 0.1.153). */
+    $nulls?: Partial<Record<string, NullsPlacement>>;
     [key: string]: unknown;
   };
 }
@@ -2577,7 +2588,15 @@ declare abstract class AsValueHelpController<T extends TAtscriptAnnotatedType =
    */
   runQuery(url: string): Promise<DataType[] | HttpError>;
   /**
-   * **GET /pages** — paginated row window plus total count.
+   * `/pages` controls without a `$sort` (since 0.1.153): ordered by the
+   * primary key, ascending, so consecutive pages neither overlap nor skip
+   * rows — like the DB controllers' `/pages`. A request with `$sort` or
+   * `$search` keeps its order; a source without a primary key stays as is.
+   */
+  private _pagesOrder;
+  /**
+   * **GET /pages** — paginated row window plus total count. Without a
+   * `$sort` the rows come in primary-key order (since 0.1.153).
    */
   runPages(url: string): Promise<{
     data: DataType[];

package/dist/index.d.mts

@@ -3,7 +3,7 @@ import { TAtscriptAnnotatedType, TAtscriptDataType, TSerializeOptions, TSerializ
 import { HttpError, MoostHttp } from "@moostjs/event-http";
 import { Mate, Moost, TConsoleBase, TMateParamMeta, TMoostMetadata } from "moost";
 import { parseUrl } from "@uniqu/url";
-import { AggregateFn, AtscriptDbReadable, AtscriptDbTable, BucketUnit, FilterExpr, FlatOf, TCrudOp, TCrudOp as TCrudOp$1, TCrudPermissions, TCrudPermissions as TCrudPermissions$1, TDbActionInfo, TDbActionInfo as TDbActionInfo$1, TDbActionIntent, TDbActionIntent as TDbActionIntent$1, TDbActionLevel, TDbActionLevel as TDbActionLevel$1, TDbActionProcessor, TDbActionTargetSummary, TDbActionTargetSummary as TDbActionTargetSummary$1, TDbAvailableActions, TDbAvailableActions as TDbAvailableActions$1, TDbFieldMeta, TDbRemoveGuardContext, TDbRemoveGuardContext as TDbRemoveGuardContext$1, TDbWriteAction, TDbWriteAction as TDbWriteAction$1, TDbWriteCheckContext, TDbWriteCheckContext as TDbWriteCheckContext$1, TDbWriteGuardContext, TDbWriteGuardContext as TDbWriteGuardContext$1, TFilterPredicate, TIdResolveOptions, TIdentification, TMetaResponse, TQueryPathOp, TQueryPathOp as TQueryPathOp$1, TQueryPathRefs, TQueryPathSource, Uniquery, UniqueryControls, collectQueryPaths } from "@atscript/db";
+import { AggregateFn, AtscriptDbReadable, AtscriptDbTable, BucketUnit, FilterExpr, FlatOf, NullsPlacement, TCrudOp, TCrudOp as TCrudOp$1, TCrudPermissions, TCrudPermissions as TCrudPermissions$1, TDbActionInfo, TDbActionInfo as TDbActionInfo$1, TDbActionIntent, TDbActionIntent as TDbActionIntent$1, TDbActionLevel, TDbActionLevel as TDbActionLevel$1, TDbActionProcessor, TDbActionTargetSummary, TDbActionTargetSummary as TDbActionTargetSummary$1, TDbAvailableActions, TDbAvailableActions as TDbAvailableActions$1, TDbFieldMeta, TDbRemoveGuardContext, TDbRemoveGuardContext as TDbRemoveGuardContext$1, TDbWriteAction, TDbWriteAction as TDbWriteAction$1, TDbWriteCheckContext, TDbWriteCheckContext as TDbWriteCheckContext$1, TDbWriteGuardContext, TDbWriteGuardContext as TDbWriteGuardContext$1, TFilterPredicate, TIdResolveOptions, TIdentification, TMetaResponse, TQueryPathOp, TQueryPathOp as TQueryPathOp$1, TQueryPathRefs, TQueryPathSource, Uniquery, UniqueryControls, collectQueryPaths } from "@atscript/db";
 import { EventContext } from "@wooksjs/event-core";
 
 //#region src/meta/meta-cache.d.ts
@@ -243,7 +243,7 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
    * keys the shared db validator plugin reads in db-client (`db.json`,
    * `db.patch.strategy`, `db.default*`, `db.column.version`,
    * `db.column.derived`) and the client-facing `db.http.path` /
-   * `db.writeOnly`; strips every other `db.*` (table, column, index, etc.).
+   * `db.writeOnly` / `db.sort.nulls`; strips every other `db.*` (table, column, index, etc.).
    * Override in subclass to customise — keep the validator keys, or client
    * preflight diverges from the server.
    */
@@ -2076,7 +2076,17 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    */
   query(url: string): Promise<DataType[] | number | HttpError>;
   /**
-   * **GET /pages** — returns paginated records with metadata.
+   * The `/pages` read without a `$sort` (since 0.1.153): ordered by the
+   * primary key, ascending, so consecutive pages neither overlap nor skip
+   * rows. A request with `$sort` keeps it (the core appends the primary key
+   * as the tie-breaker); a source without a primary key (a view without
+   * `@meta.id`) stays unordered. Only the plain read: text / vector search
+   * keep their relevance order.
+   */
+  private _pagesOrder;
+  /**
+   * **GET /pages** — returns paginated records with metadata. Without a
+   * `$sort` the rows come in primary-key order (since 0.1.153).
    */
   pages(url: string): Promise<{
     data: DataType[];
@@ -2464,7 +2474,8 @@ interface ValueHelpQuery<T> {
     $limit?: number;
     $search?: string;
     $select?: (keyof T | string)[];
-    $sort?: unknown;
+    $sort?: unknown; /** NULL placement per `$sort` key (URL `$sort=-name:last`; since 0.1.153). */
+    $nulls?: Partial<Record<string, NullsPlacement>>;
     [key: string]: unknown;
   };
 }
@@ -2577,7 +2588,15 @@ declare abstract class AsValueHelpController<T extends TAtscriptAnnotatedType =
    */
   runQuery(url: string): Promise<DataType[] | HttpError>;
   /**
-   * **GET /pages** — paginated row window plus total count.
+   * `/pages` controls without a `$sort` (since 0.1.153): ordered by the
+   * primary key, ascending, so consecutive pages neither overlap nor skip
+   * rows — like the DB controllers' `/pages`. A request with `$sort` or
+   * `$search` keeps its order; a source without a primary key stays as is.
+   */
+  private _pagesOrder;
+  /**
+   * **GET /pages** — paginated row window plus total count. Without a
+   * `$sort` the rows come in primary-key order (since 0.1.153).
    */
   runPages(url: string): Promise<{
     data: DataType[];

package/dist/index.mjs

@@ -84,6 +84,9 @@ const dbErrorCodeToStatus = {
 	CAS_MISMATCH: 409,
 	TX_WAIT_TIMEOUT: 503,
 	SPACE_CLOSED: 503,
+	DEADLOCK: 503,
+	LOCK_TIMEOUT: 503,
+	SERIALIZATION_FAILURE: 503,
 	BUCKET_TZ_UNAVAILABLE: 501
 };
 function transformValidationError(error, reply) {
@@ -167,6 +170,15 @@ var SortControlDto = class {
 		throwFeatureDisabled("JSON Schema", "jsonSchema", "emit.jsonSchema");
 	}
 };
+var NullsControlDto = class {
+	static __is_atscript_annotated_type = true;
+	static type = {};
+	static metadata = /* @__PURE__ */ new Map();
+	static id = "NullsControlDto";
+	static toJsonSchema() {
+		throwFeatureDisabled("JSON Schema", "jsonSchema", "emit.jsonSchema");
+	}
+};
 var SelectControlDto = class {
 	static __is_atscript_annotated_type = true;
 	static type = {};
@@ -176,7 +188,7 @@ var SelectControlDto = class {
 		throwFeatureDisabled("JSON Schema", "jsonSchema", "emit.jsonSchema");
 	}
 };
-defineAnnotatedType("object", QueryControlsDto).prop("$skip", defineAnnotatedType().designType("number").tags("positive", "int", "number").annotate("expect.int", true).annotate("expect.min", { minValue: 0 }).optional().$type).prop("$limit", defineAnnotatedType().designType("number").tags("positive", "int", "number").annotate("expect.int", true).annotate("expect.min", { minValue: 0 }).optional().$type).prop("$count", defineAnnotatedType().designType("boolean").tags("boolean").optional().$type).prop("$sort", defineAnnotatedType().refTo(SortControlDto).optional().$type).prop("$select", defineAnnotatedType("union").item(defineAnnotatedType().refTo(SelectControlDto).$type).item(defineAnnotatedType("array").of(defineAnnotatedType().designType("string").tags("string").$type).$type).optional().$type).prop("$search", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$index", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$fuzzy", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$vector", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$threshold", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$with", defineAnnotatedType("array").of(defineAnnotatedType().refTo(WithRelationDto).$type).optional().$type).prop("$actions", defineAnnotatedType().designType("boolean").tags("boolean").optional().$type);
+defineAnnotatedType("object", QueryControlsDto).prop("$skip", defineAnnotatedType().designType("number").tags("positive", "int", "number").annotate("expect.int", true).annotate("expect.min", { minValue: 0 }).optional().$type).prop("$limit", defineAnnotatedType().designType("number").tags("positive", "int", "number").annotate("expect.int", true).annotate("expect.min", { minValue: 0 }).optional().$type).prop("$count", defineAnnotatedType().designType("boolean").tags("boolean").optional().$type).prop("$sort", defineAnnotatedType().refTo(SortControlDto).optional().$type).prop("$nulls", defineAnnotatedType().refTo(NullsControlDto).optional().$type).prop("$select", defineAnnotatedType("union").item(defineAnnotatedType().refTo(SelectControlDto).$type).item(defineAnnotatedType("array").of(defineAnnotatedType().designType("string").tags("string").$type).$type).optional().$type).prop("$search", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$index", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$fuzzy", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$vector", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$threshold", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$with", defineAnnotatedType("array").of(defineAnnotatedType().refTo(WithRelationDto).$type).optional().$type).prop("$actions", defineAnnotatedType().designType("boolean").tags("boolean").optional().$type);
 defineAnnotatedType("object", PagesControlsDto).prop("$page", defineAnnotatedType().designType("string").tags("string").annotate("expect.pattern", {
 	pattern: "^\\d+$",
 	flags: "u",
@@ -185,7 +197,7 @@ defineAnnotatedType("object", PagesControlsDto).prop("$page", defineAnnotatedTyp
 	pattern: "^\\d+$",
 	flags: "u",
 	message: "Expected positive number"
-}, true).optional().$type).prop("$sort", defineAnnotatedType().refTo(SortControlDto).optional().$type).prop("$select", defineAnnotatedType("union").item(defineAnnotatedType().refTo(SelectControlDto).$type).item(defineAnnotatedType("array").of(defineAnnotatedType().designType("string").tags("string").$type).$type).optional().$type).prop("$search", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$index", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$fuzzy", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$vector", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$threshold", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$with", defineAnnotatedType("array").of(defineAnnotatedType().refTo(WithRelationDto).$type).optional().$type).prop("$actions", defineAnnotatedType().designType("boolean").tags("boolean").optional().$type);
+}, true).optional().$type).prop("$sort", defineAnnotatedType().refTo(SortControlDto).optional().$type).prop("$nulls", defineAnnotatedType().refTo(NullsControlDto).optional().$type).prop("$select", defineAnnotatedType("union").item(defineAnnotatedType().refTo(SelectControlDto).$type).item(defineAnnotatedType("array").of(defineAnnotatedType().designType("string").tags("string").$type).$type).optional().$type).prop("$search", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$index", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$fuzzy", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$vector", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$threshold", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$with", defineAnnotatedType("array").of(defineAnnotatedType().refTo(WithRelationDto).$type).optional().$type).prop("$actions", defineAnnotatedType().designType("boolean").tags("boolean").optional().$type);
 defineAnnotatedType("object", GetOneControlsDto).prop("$select", defineAnnotatedType("union").item(defineAnnotatedType().refTo(SelectControlDto).$type).item(defineAnnotatedType("array").of(defineAnnotatedType().designType("string").tags("string").$type).$type).optional().$type).prop("$with", defineAnnotatedType("array").of(defineAnnotatedType().refTo(WithRelationDto).$type).optional().$type).prop("$actions", defineAnnotatedType().designType("boolean").tags("boolean").optional().$type);
 defineAnnotatedType("object", GeoControlsDto).prop("$center", defineAnnotatedType("union").item(defineAnnotatedType().designType("string").tags("string").$type).item(defineAnnotatedType("array").of(defineAnnotatedType().designType("string").tags("string").$type).$type).item(defineAnnotatedType("array").of(defineAnnotatedType().designType("number").tags("number").$type).$type).optional().$type).prop("$maxDistance", defineAnnotatedType().designType("number").tags("number").optional().$type).prop("$minDistance", defineAnnotatedType().designType("number").tags("number").optional().$type).prop("$index", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$select", defineAnnotatedType("union").item(defineAnnotatedType().refTo(SelectControlDto).$type).item(defineAnnotatedType("array").of(defineAnnotatedType().designType("string").tags("string").$type).$type).optional().$type).prop("$skip", defineAnnotatedType().designType("number").tags("positive", "int", "number").annotate("expect.int", true).annotate("expect.min", { minValue: 0 }).optional().$type).prop("$limit", defineAnnotatedType().designType("number").tags("positive", "int", "number").annotate("expect.int", true).annotate("expect.min", { minValue: 0 }).optional().$type).prop("$page", defineAnnotatedType().designType("string").tags("string").annotate("expect.pattern", {
 	pattern: "^\\d+$",
@@ -197,9 +209,10 @@ defineAnnotatedType("object", GeoControlsDto).prop("$center", defineAnnotatedTyp
 	message: "Expected positive number"
 }, true).optional().$type).prop("$with", defineAnnotatedType("array").of(defineAnnotatedType().refTo(WithRelationDto).$type).optional().$type).prop("$actions", defineAnnotatedType().designType("boolean").tags("boolean").optional().$type);
 defineAnnotatedType("object", WithRelationDto).prop("name", defineAnnotatedType().designType("string").tags("string").$type).prop("filter", defineAnnotatedType().refTo(WithFilterDto).optional().$type).prop("controls", defineAnnotatedType().refTo(WithRelationControlsDto).optional().$type).prop("insights", defineAnnotatedType().refTo(WithFilterDto).optional().$type);
-defineAnnotatedType("object", WithRelationControlsDto).prop("$skip", defineAnnotatedType().designType("number").tags("positive", "int", "number").annotate("expect.int", true).annotate("expect.min", { minValue: 0 }).optional().$type).prop("$limit", defineAnnotatedType().designType("number").tags("positive", "int", "number").annotate("expect.int", true).annotate("expect.min", { minValue: 0 }).optional().$type).prop("$sort", defineAnnotatedType().refTo(SortControlDto).optional().$type).prop("$select", defineAnnotatedType("union").item(defineAnnotatedType().refTo(SelectControlDto).$type).item(defineAnnotatedType("array").of(defineAnnotatedType().designType("string").tags("string").$type).$type).optional().$type).prop("$with", defineAnnotatedType("array").of(defineAnnotatedType().refTo(WithRelationDto).$type).optional().$type);
+defineAnnotatedType("object", WithRelationControlsDto).prop("$skip", defineAnnotatedType().designType("number").tags("positive", "int", "number").annotate("expect.int", true).annotate("expect.min", { minValue: 0 }).optional().$type).prop("$limit", defineAnnotatedType().designType("number").tags("positive", "int", "number").annotate("expect.int", true).annotate("expect.min", { minValue: 0 }).optional().$type).prop("$sort", defineAnnotatedType().refTo(SortControlDto).optional().$type).prop("$nulls", defineAnnotatedType().refTo(NullsControlDto).optional().$type).prop("$select", defineAnnotatedType("union").item(defineAnnotatedType().refTo(SelectControlDto).$type).item(defineAnnotatedType("array").of(defineAnnotatedType().designType("string").tags("string").$type).$type).optional().$type).prop("$with", defineAnnotatedType("array").of(defineAnnotatedType().refTo(WithRelationDto).$type).optional().$type);
 defineAnnotatedType("object", WithFilterDto).propPattern(/./, defineAnnotatedType("union").item(defineAnnotatedType().designType("string").tags("string").$type).item(defineAnnotatedType().designType("number").tags("number").$type).item(defineAnnotatedType().designType("boolean").tags("boolean").$type).item(defineAnnotatedType().designType("null").tags("null").$type).item(defineAnnotatedType().refTo(WithFilterDto).$type).item(defineAnnotatedType("array").of(defineAnnotatedType().refTo(WithFilterDto).$type).$type).$type);
 defineAnnotatedType("object", SortControlDto).propPattern(/./, defineAnnotatedType("union").item(defineAnnotatedType().designType("number").value(1).$type).item(defineAnnotatedType().designType("number").value(-1).$type).$type);
+defineAnnotatedType("object", NullsControlDto).propPattern(/./, defineAnnotatedType("union").item(defineAnnotatedType().designType("string").value("first").$type).item(defineAnnotatedType().designType("string").value("last").$type).$type);
 defineAnnotatedType("object", SelectControlDto).propPattern(/./, defineAnnotatedType("union").item(defineAnnotatedType().designType("number").value(1).$type).item(defineAnnotatedType().designType("number").value(0).$type).$type);
 //#endregion
 //#region src/mate.ts
@@ -2860,7 +2873,7 @@ let AsReadableController = _AsReadableController = class AsReadableController {
 	* keys the shared db validator plugin reads in db-client (`db.json`,
 	* `db.patch.strategy`, `db.default*`, `db.column.version`,
 	* `db.column.derived`) and the client-facing `db.http.path` /
-	* `db.writeOnly`; strips every other `db.*` (table, column, index, etc.).
+	* `db.writeOnly` / `db.sort.nulls`; strips every other `db.*` (table, column, index, etc.).
 	* Override in subclass to customise — keep the validator keys, or client
 	* preflight diverges from the server.
 	*/
@@ -2872,7 +2885,7 @@ let AsReadableController = _AsReadableController = class AsReadableController {
 					key,
 					value
 				};
-				if (key === "db.json" || key === "db.patch.strategy" || key.startsWith("db.default") || key === "db.http.path" || key === "db.writeOnly" || key === "db.column.version" || key === "db.column.derived") return {
+				if (key === "db.json" || key === "db.patch.strategy" || key.startsWith("db.default") || key === "db.http.path" || key === "db.writeOnly" || key === "db.column.version" || key === "db.column.derived" || key === "db.sort.nulls") return {
 					key,
 					value
 				};
@@ -5335,7 +5348,10 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 				if (sealed.size === 0) return void 0;
 				const refs = collectQueryPaths$1({
 					filter: rel.filter,
-					controls: { $sort: nested.$sort ?? rel.$sort }
+					controls: {
+						$sort: nested.$sort ?? rel.$sort,
+						$nulls: nested.$nulls ?? rel.$nulls
+					}
 				});
 				const filtered = refs.filter.find((ref) => selfOrAncestor(ref.path, sealed) !== void 0)?.path;
 				if (filtered !== void 0) return writeOnlyError(`${path}.${filtered}`, "filter");
@@ -7050,7 +7066,29 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 		})).data;
 	}
 	/**
-	* **GET /pages** — returns paginated records with metadata.
+	* The `/pages` read without a `$sort` (since 0.1.153): ordered by the
+	* primary key, ascending, so consecutive pages neither overlap nor skip
+	* rows. A request with `$sort` keeps it (the core appends the primary key
+	* as the tie-breaker); a source without a primary key (a view without
+	* `@meta.id`) stays unordered. Only the plain read: text / vector search
+	* keep their relevance order.
+	*/
+	_pagesOrder(q) {
+		const controls = q.controls;
+		const sort = controls?.$sort;
+		const pk = this.readable.primaryKeys;
+		if (sort && Object.keys(sort).length > 0 || pk.length === 0) return q;
+		return {
+			...q,
+			controls: {
+				...controls,
+				$sort: Object.fromEntries(pk.map((f) => [f, 1]))
+			}
+		};
+	}
+	/**
+	* **GET /pages** — returns paginated records with metadata. Without a
+	* `$sort` the rows come in primary-key order (since 0.1.153).
 	*/
 	async pages(url) {
 		const { parsed, controls } = await this.parseRequest("pages", url);
@@ -7077,7 +7115,7 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 			switch (strategy.kind) {
 				case "vector": return strategy.vectorField ? this.readable.vectorSearchWithCount(strategy.vectorField, strategy.vector, q) : this.readable.vectorSearchWithCount(strategy.vector, q);
 				case "search": return this.readable.searchWithCount(strategy.term, q, strategy.index);
-				case "plain": return this.readable.findManyWithCount(q);
+				case "plain": return this.readable.findManyWithCount(this._pagesOrder(q));
 			}
 		});
 		return {
@@ -7561,7 +7599,8 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 			versionColumn: this.readable.versionColumn,
 			...capabilities.bucketUnits.length > 0 && { bucketUnits: [...capabilities.bucketUnits] },
 			aggregateFns: [...capabilities.aggregateFns],
-			aggregateExpressions: capabilities.aggregateExpressions
+			aggregateExpressions: capabilities.aggregateExpressions,
+			...typeof this.readable.supportsNullsPlacement === "function" && this.readable.supportsNullsPlacement() && { nullsPlacement: true }
 		};
 	}
 	buildCrud() {
@@ -8161,7 +8200,22 @@ let AsValueHelpController = class AsValueHelpController extends AsReadableContro
 		return (await this.query(await this._scopedQuery(parsed.filter, controls))).data;
 	}
 	/**
-	* **GET /pages** — paginated row window plus total count.
+	* `/pages` controls without a `$sort` (since 0.1.153): ordered by the
+	* primary key, ascending, so consecutive pages neither overlap nor skip
+	* rows — like the DB controllers' `/pages`. A request with `$sort` or
+	* `$search` keeps its order; a source without a primary key stays as is.
+	*/
+	_pagesOrder(controls) {
+		const sort = controls.$sort;
+		if ((Array.isArray(sort) ? sort.length > 0 : isPlainObject(sort) ? !isEmptyObject(sort) : !!sort) || controls.$search || !this.primaryKey) return controls;
+		return {
+			...controls,
+			$sort: { [this.primaryKey]: 1 }
+		};
+	}
+	/**
+	* **GET /pages** — paginated row window plus total count. Without a
+	* `$sort` the rows come in primary-key order (since 0.1.153).
 	*/
 	async runPages(url) {
 		const { parsed, controls } = await this.parseRequest("pages", url);
@@ -8170,11 +8224,11 @@ let AsValueHelpController = class AsValueHelpController extends AsReadableContro
 		const page = Math.max(Number(controls.$page || 1), 1);
 		const size = Math.max(Number(controls.$size || 10), 1);
 		const skip = (page - 1) * size;
-		const result = await this.query(await this._scopedQuery(parsed.filter, {
+		const result = await this.query(await this._scopedQuery(parsed.filter, this._pagesOrder({
 			...controls,
 			$skip: skip,
 			$limit: size
-		}));
+		})));
 		return {
 			data: result.data,
 			page,
@@ -8314,7 +8368,7 @@ let AsJsonValueHelpController = class AsJsonValueHelpController extends AsValueH
 			rows = rows.filter((row) => predicate(row));
 		}
 		const sort = this.normalizeSort(controls.controls.$sort);
-		if (sort) rows = sortRows(rows, sort);
+		if (sort) rows = sortRows(rows, sort, void 0, void 0, controls.controls.$nulls);
 		const total = rows.length;
 		const skip = Math.max(0, Number(controls.controls.$skip ?? 0));
 		const limit = Math.max(0, Number(controls.controls.$limit ?? total - skip));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/moost-db",
-  "version": "0.1.152",
+  "version": "0.1.153",
   "description": "Generic database controller for Moost with Atscript.",
   "keywords": [
     "annotations",
@@ -43,30 +43,30 @@
     "access": "public"
   },
   "dependencies": {
-    "@uniqu/url": "^0.1.14",
-    "@atscript/db-memory": "^0.1.152"
+    "@uniqu/url": "^0.1.15",
+    "@atscript/db-memory": "^0.1.153"
   },
   "devDependencies": {
-    "@atscript/core": "^0.1.102",
-    "@atscript/typescript": "^0.1.102",
-    "@moostjs/event-http": "^0.6.48",
-    "@uniqu/core": "^0.1.14",
-    "@wooksjs/event-core": "^0.7.27",
-    "@wooksjs/event-http": "^0.7.27",
-    "@wooksjs/http-body": "^0.7.27",
+    "@atscript/core": "^0.1.103",
+    "@atscript/typescript": "^0.1.103",
+    "@moostjs/event-http": "^0.6.49",
+    "@uniqu/core": "^0.1.15",
+    "@wooksjs/event-core": "^0.7.28",
+    "@wooksjs/event-http": "^0.7.28",
+    "@wooksjs/http-body": "^0.7.28",
     "better-sqlite3": "^12.6.2",
-    "moost": "^0.6.48",
-    "unplugin-atscript": "^0.1.102",
-    "@atscript/db-sqlite": "^0.1.152"
+    "moost": "^0.6.49",
+    "unplugin-atscript": "^0.1.103",
+    "@atscript/db-sqlite": "^0.1.153"
   },
   "peerDependencies": {
-    "@atscript/typescript": "^0.1.102",
-    "@moostjs/event-http": "^0.6.48",
-    "@uniqu/core": "^0.1.14",
-    "@wooksjs/event-core": "^0.7.27",
-    "@wooksjs/http-body": "^0.7.27",
-    "moost": "^0.6.48",
-    "@atscript/db": "^0.1.152"
+    "@atscript/typescript": "^0.1.103",
+    "@moostjs/event-http": "^0.6.49",
+    "@uniqu/core": "^0.1.15",
+    "@wooksjs/event-core": "^0.7.28",
+    "@wooksjs/http-body": "^0.7.28",
+    "moost": "^0.6.49",
+    "@atscript/db": "^0.1.153"
   },
   "scripts": {
     "postinstall": "asc -f dts",