@classytic/repo-core 0.31.1 → 0.32.0

package/dist/pagination/keyset.d.mts

@@ -1,5 +1,4 @@
 import { SortSpec } from "./types.mjs";
-//#region src/pagination/keyset.d.ts
 /**
  * Normalize a sort object so non-`_id` fields come first, `_id` last.
  * Stable ordering is required for cursor comparability across requests.
@@ -20,5 +19,4 @@ declare function validateKeysetSort(sort: SortSpec, allowedPrimaryFields?: reado
 declare function invertSort(sort: SortSpec): SortSpec;
 /** Primary (first non-`_id`) sort field; falls back to `_id`. */
 declare function getPrimaryField(sort: SortSpec): string;
-//#endregion
 export { getPrimaryField, invertSort, normalizeSort, validateKeysetSort };

package/dist/pagination/keyset.mjs

@@ -1,4 +1,4 @@
-//#region src/pagination/keyset.ts
+// src/pagination/keyset.ts
 /**
 * Normalize a sort object so non-`_id` fields come first, `_id` last.
 * Stable ordering is required for cursor comparability across requests.
@@ -55,5 +55,4 @@ function getPrimaryField(sort) {
 	for (const key of Object.keys(sort)) if (key !== "_id") return key;
 	return "_id";
 }
-//#endregion
 export { getPrimaryField, invertSort, normalizeSort, validateKeysetSort };

package/dist/pagination/merge-keyset.d.mts

@@ -1,4 +1,3 @@
-//#region src/pagination/merge-keyset.d.ts
 /**
  * `mergeKeysetPages`: one keyset page over SEVERAL sources, each already ordered by the same total
  * order, merged by the sort key with source order as the final tiebreaker. Each call reads at most
@@ -46,5 +45,4 @@ interface MergedKeysetPage<T> {
   hasNext: boolean;
 }
 declare function mergeKeysetPages<T>(sources: readonly KeysetSource<T>[], options: MergeKeysetOptions<T>): Promise<MergedKeysetPage<T>>;
-//#endregion
 export { KeysetSource, MergeKeysetOptions, MergedKeysetPage, mergeKeysetPages };

package/dist/pagination/merge-keyset.mjs

@@ -1,7 +1,7 @@
 import { CURSOR_ERROR_CODES } from "../errors/codes.mjs";
 import { createError } from "../errors/create-error.mjs";
 import { createHash, createHmac, timingSafeEqual } from "node:crypto";
-//#region src/pagination/merge-keyset.ts
+// src/pagination/merge-keyset.ts
 /**
 * `mergeKeysetPages`: one keyset page over SEVERAL sources, each already ordered by the same total
 * order, merged by the sort key with source order as the final tiebreaker. Each call reads at most
@@ -135,5 +135,4 @@ async function mergeKeysetPages(sources, options) {
 		}, secret) : null
 	};
 }
-//#endregion
 export { mergeKeysetPages };

package/dist/pagination/offset.d.mts

@@ -1,5 +1,4 @@
 import { PaginationConfig } from "./types.mjs";
-//#region src/pagination/offset.d.ts
 /**
  * Parse, clamp, and sanitize a `limit` value. Accepts string or number
  * input (URL params arrive as strings). Returns the configured default
@@ -21,5 +20,4 @@ declare function shouldWarnDeepPagination(page: number, threshold: number): bool
 declare function calculateSkip(page: number, limit: number): number;
 /** Total page count from total rows + per-page limit. Zero-safe. */
 declare function calculateTotalPages(total: number, limit: number): number;
-//#endregion
 export { calculateSkip, calculateTotalPages, shouldWarnDeepPagination, validateLimit, validatePage };

package/dist/pagination/offset.mjs

@@ -1,4 +1,4 @@
-//#region src/pagination/offset.ts
+// src/pagination/offset.ts
 const DEFAULT_LIMIT = 10;
 const DEFAULT_MAX_LIMIT = 100;
 const DEFAULT_MAX_PAGE = 1e4;
@@ -43,5 +43,4 @@ function calculateTotalPages(total, limit) {
 	if (limit <= 0) return 0;
 	return Math.ceil(total / limit);
 }
-//#endregion
 export { calculateSkip, calculateTotalPages, shouldWarnDeepPagination, validateLimit, validatePage };

package/dist/pagination/types.d.mts

@@ -1,4 +1,3 @@
-//#region src/pagination/types.d.ts
 /**
  * Pagination primitives — driver-agnostic type surface.
  *
@@ -204,5 +203,4 @@ interface BareListResult<TDoc> {
  * (HTTP status >= 400 → `ErrorContract`).
  */
 type PaginatedResult<TDoc, TExtra extends Record<string, unknown> = {}> = OffsetPaginationResult<TDoc, TExtra> | KeysetPaginationResult<TDoc, TExtra> | AggregatePaginationResult<TDoc, TExtra> | BareListResult<TDoc>;
-//#endregion
 export { AggregatePaginationResult, AggregatePaginationResultCore, AnyPaginationResult, BareListResult, CursorPayload, DecodedCursor, KeysetPaginationResult, KeysetPaginationResultCore, OffsetPaginationResult, OffsetPaginationResultCore, PaginatedResult, PaginationConfig, SortDirection, SortSpec, ValueType };

package/dist/plugins/index.mjs

@@ -1,2 +1 @@
-import { adminBypass, payloadHasTenantField } from "./tenant-helpers.mjs";
-export { adminBypass, payloadHasTenantField };
+export { adminBypass, payloadHasTenantField } from "./tenant-helpers.mjs";

package/dist/plugins/tenant-helpers.d.mts

@@ -1,5 +1,4 @@
 import { PolicyKey } from "../operations/types.mjs";
-//#region src/plugins/tenant-helpers.d.ts
 /**
  * Minimal context shape this module reads. Kits' richer
  * `RepositoryContext` types extend this — by accepting only the slots
@@ -58,5 +57,4 @@ declare function adminBypass(options: {
   roleField?: string;
   adminRoles: readonly string[];
 }): (context: Record<string, unknown>, operation: string) => boolean;
-//#endregion
 export { TenantPolicyContext, adminBypass, payloadHasTenantField };

package/dist/plugins/tenant-helpers.mjs

@@ -1,4 +1,4 @@
-//#region src/plugins/tenant-helpers.ts
+// src/plugins/tenant-helpers.ts
 /**
 * True when the op's policy target already has `tenantField` set by
 * the caller. Used to decide whether the plugin can safely skip
@@ -80,5 +80,4 @@ function adminBypass(options) {
 		return typeof role === "string" && allowed.has(role);
 	};
 }
-//#endregion
 export { adminBypass, payloadHasTenantField };

package/dist/query-parser/coerce.d.mts

@@ -1,4 +1,3 @@
-//#region src/query-parser/coerce.d.ts
 /**
  * URL value → typed scalar. A declared field type wins, and a value that does not fit it is
  * refused. Without one, a conservative heuristic applies: never a leading-zero code (`007`), never a
@@ -18,5 +17,4 @@ interface CoerceOptions {
   param: string;
 }
 declare function coerceQueryValue(raw: string, options: CoerceOptions): QueryScalar;
-//#endregion
 export { CoerceOptions, QueryFieldType, QueryScalar, coerceQueryValue };

package/dist/query-parser/coerce.mjs

@@ -1,6 +1,6 @@
 import { ISO_DATE_PATTERN } from "../filter/coerce-dates.mjs";
 import { QueryGrammarError } from "./errors.mjs";
-//#region src/query-parser/coerce.ts
+// src/query-parser/coerce.ts
 /**
 * URL value → typed scalar. A declared field type wins, and a value that does not fit it is
 * refused. Without one, a conservative heuristic applies: never a leading-zero code (`007`), never a
@@ -44,5 +44,4 @@ function toDate(raw) {
 function fail(param, reason) {
 	throw new QueryGrammarError(param, reason);
 }
-//#endregion
 export { coerceQueryValue };

package/dist/query-parser/errors.d.mts

@@ -1,5 +1,4 @@
 import { HttpError, ValidationErrorMeta } from "../errors/types.mjs";
-//#region src/query-parser/errors.d.ts
 /** The code every query-grammar refusal carries — stable across parsers and kits. */
 declare const INVALID_QUERY_INPUT = "INVALID_QUERY_INPUT";
 /**
@@ -26,5 +25,4 @@ declare class QueryGrammarError extends Error implements HttpError {
   constructor(param: string, reason: string, kind?: QueryErrorKind);
 }
 declare function isQueryGrammarError(value: unknown): value is QueryGrammarError;
-//#endregion
 export { INVALID_QUERY_INPUT, QueryErrorKind, QueryGrammarError, isQueryGrammarError };

package/dist/query-parser/errors.mjs

@@ -1,4 +1,4 @@
-//#region src/query-parser/errors.ts
+// src/query-parser/errors.ts
 /** The code every query-grammar refusal carries — stable across parsers and kits. */
 const INVALID_QUERY_INPUT = "INVALID_QUERY_INPUT";
 /**
@@ -28,5 +28,4 @@ var QueryGrammarError = class extends Error {
 function isQueryGrammarError(value) {
 	return value instanceof Error && value.code === "INVALID_QUERY_INPUT";
 }
-//#endregion
 export { INVALID_QUERY_INPUT, QueryGrammarError, isQueryGrammarError };

package/dist/query-parser/format-query.d.mts

@@ -0,0 +1,30 @@
+import { BracketOperator } from "./types.mjs";
+/** Operators a filter term can use: every URL operator except `options` (regex flags ride on `flags`). */
+type FilterOperator = Exclude<BracketOperator, 'options'>;
+/** One typed filter. `op` defaults to `eq`. */
+interface FilterTerm {
+  field: string;
+  op?: FilterOperator;
+  /**
+   * `in`/`nin`: array. `between`: `[from, to]` (either side may be empty). `exists`: boolean.
+   * Otherwise a string, number, boolean, `Date` or `null`.
+   */
+  value?: unknown;
+  /** `regex` only: flags from `i`, `m`, `s`, `x`. */
+  flags?: string;
+}
+interface FormatQueryInput {
+  filters?: readonly FilterTerm[];
+  /** `'-createdAt'`, `'name'` or a list of them. */
+  sort?: string | readonly string[];
+  page?: number;
+  limit?: number;
+  /** Free-text search, trimmed; empty is omitted. */
+  search?: string;
+}
+/** Flat params in the shape `parseUrl` takes and Fastify/qs produce. */
+type QueryParams = Record<string, string>;
+declare function formatQuery(input: FormatQueryInput): QueryParams;
+/** {@link formatQuery} as a query string, without the leading `?`. */
+declare function stringifyQuery(input: FormatQueryInput): string;
+export { FilterOperator, FilterTerm, FormatQueryInput, QueryParams, formatQuery, stringifyQuery };

package/dist/query-parser/format-query.mjs

@@ -0,0 +1,90 @@
+import { QueryGrammarError } from "./errors.mjs";
+import { URL_OPERATORS } from "./grammar.mjs";
+// src/query-parser/format-query.ts
+/**
+* Typed filters -> the URL params {@link parseUrl} accepts: the inverse of the grammar in
+* `./grammar.ts`, client-safe, built from the same operator constants.
+*
+*   formatQuery({ filters: [{ field: 'age', op: 'gte', value: 18 }], sort: '-createdAt' })
+*     -> { 'age[gte]': '18', sort: '-createdAt' }
+*
+* An empty value (`''`, `undefined`, `[]`) is no filter, as the parser reads it. `between` is sent
+* as `gte` + `lte`. A value the grammar cannot carry is refused, never sent mangled.
+*/
+const FIELD_RE = /^[A-Za-z_][A-Za-z0-9_-]*(?:\.[A-Za-z0-9_-]+)*$/;
+function formatQuery(input) {
+	const out = {};
+	const put = (key, value) => {
+		if (key in out) throw new QueryGrammarError(key, "sent twice (one term per field and operator)", "syntax");
+		out[key] = value;
+	};
+	for (const term of input.filters ?? []) writeTerm(term, put);
+	if (input.sort !== void 0) {
+		const sort = (Array.isArray(input.sort) ? input.sort : [input.sort]).join(",");
+		if (sort) out["sort"] = sort;
+	}
+	if (input.page !== void 0) out["page"] = positive("page", input.page);
+	if (input.limit !== void 0) out["limit"] = positive("limit", input.limit);
+	const search = input.search?.trim();
+	if (search) out["search"] = search;
+	return out;
+}
+/** {@link formatQuery} as a query string, without the leading `?`. */
+function stringifyQuery(input) {
+	return new URLSearchParams(formatQuery(input)).toString();
+}
+function writeTerm(term, put) {
+	const { field, value } = term;
+	const op = term.op ?? "eq";
+	if (!FIELD_RE.test(field)) throw new QueryGrammarError(field, "not a field path", "syntax");
+	if (!URL_OPERATORS.includes(op) || op === "options") throw new QueryGrammarError(field, `unknown operator "${String(op)}"`, "syntax");
+	const key = (o) => o === "eq" ? field : `${field}[${o}]`;
+	if (value === void 0 || value === "" || Array.isArray(value) && value.length === 0) return;
+	switch (op) {
+		case "in":
+		case "nin": {
+			if (!Array.isArray(value)) throw new QueryGrammarError(key(op), `${op} takes an array`);
+			const items = value.map((v) => scalar(v, key(op)));
+			if (items.some((item) => item.includes(","))) throw new QueryGrammarError(key(op), "a list value cannot contain a comma");
+			put(key(op), items.join(","));
+			return;
+		}
+		case "between": {
+			if (!Array.isArray(value) || value.length !== 2) throw new QueryGrammarError(key(op), "between takes [from, to]");
+			const [from, to] = value;
+			if (from !== void 0 && from !== "" && from !== null) put(key("gte"), scalar(from, key("gte")));
+			if (to !== void 0 && to !== "" && to !== null) put(key("lte"), scalar(to, key("lte")));
+			return;
+		}
+		case "exists":
+			if (typeof value !== "boolean") throw new QueryGrammarError(key(op), "exists takes a boolean");
+			put(key(op), String(value));
+			return;
+		default:
+			put(key(op), scalar(value, key(op)));
+			if (op === "regex" && term.flags) {
+				if (!/^[imsx]+$/.test(term.flags)) throw new QueryGrammarError(`${field}[options]`, "flags must be from i, m, s, x");
+				put(`${field}[options]`, term.flags);
+			}
+	}
+}
+function scalar(value, param) {
+	if (value === null) return "null";
+	if (value instanceof Date) {
+		if (Number.isNaN(value.getTime())) throw new QueryGrammarError(param, "invalid Date");
+		return value.toISOString();
+	}
+	if (typeof value === "number") {
+		if (!Number.isFinite(value)) throw new QueryGrammarError(param, "not a finite number");
+		return String(value);
+	}
+	if (typeof value === "boolean") return String(value);
+	if (typeof value !== "string") throw new QueryGrammarError(param, "a filter value is a string, number, boolean, Date or null");
+	if (value === "null") throw new QueryGrammarError(param, "the text \"null\" reads as null");
+	return value;
+}
+function positive(param, value) {
+	if (!Number.isSafeInteger(value) || value < 1) throw new QueryGrammarError(param, `"${String(value)}" is not a positive integer`);
+	return String(value);
+}
+export { formatQuery, stringifyQuery };

package/dist/query-parser/grammar.d.mts

@@ -2,7 +2,6 @@ import { Filter } from "../filter/types.mjs";
 import { QueryFieldType, QueryScalar } from "./coerce.mjs";
 import { QueryGrammarError } from "./errors.mjs";
 import { BracketOperator, ParsedSelect, ParsedSort } from "./types.mjs";
-//#region src/query-parser/grammar.d.ts
 declare const DEFAULT_LIMIT = 20;
 declare const DEFAULT_MAX_LIMIT = 1000;
 declare const DEFAULT_MAX_TEXT_LENGTH = 500;
@@ -109,5 +108,4 @@ declare function readSearch(raw: unknown, options?: {
 }): string | undefined;
 /** Every input shape → one record: repeated URL keys become arrays, qs objects stay nested. */
 declare function toRecord(input: QueryInput | null | undefined): Record<string, unknown>;
-//#endregion
 export { CORE_OPERATORS, CoreOperator, DEFAULT_LIMIT, DEFAULT_MAX_LIMIT, DEFAULT_MAX_SEARCH_LENGTH, DEFAULT_MAX_TEXT_LENGTH, ExtensionClause, FilterClause, FilterReadResult, OPERATOR_DESCRIPTIONS, PageOptions, PageRequest, QueryGrammarOptions, QueryInput, URL_OPERATORS, clausesToFilter, readFilterClauses, readPageRequest, readSearch, readSelect, readSort, toRecord };

package/dist/query-parser/grammar.mjs

@@ -3,7 +3,7 @@ import { QueryGrammarError } from "./errors.mjs";
 import { coerceQueryValue } from "./coerce.mjs";
 import { assessRegex } from "./regex-safety.mjs";
 import { STANDARD_RESERVED_PARAMS } from "./reserved.mjs";
-//#region src/query-parser/grammar.ts
+// src/query-parser/grammar.ts
 const DEFAULT_LIMIT = 20;
 const DEFAULT_MAX_LIMIT = 1e3;
 const DEFAULT_MAX_TEXT_LENGTH = 500;
@@ -475,5 +475,4 @@ function cursorValue(raw) {
 	const value = String(raw).trim();
 	return value === "" ? void 0 : value;
 }
-//#endregion
 export { CORE_OPERATORS, DEFAULT_LIMIT, DEFAULT_MAX_LIMIT, DEFAULT_MAX_SEARCH_LENGTH, DEFAULT_MAX_TEXT_LENGTH, OPERATOR_DESCRIPTIONS, URL_OPERATORS, clausesToFilter, readFilterClauses, readPageRequest, readSearch, readSelect, readSort, toRecord };

package/dist/query-parser/index.d.mts

@@ -1,8 +1,9 @@
 import { CoerceOptions, QueryFieldType, QueryScalar, coerceQueryValue } from "./coerce.mjs";
 import { INVALID_QUERY_INPUT, QueryErrorKind, QueryGrammarError, isQueryGrammarError } from "./errors.mjs";
 import { BracketOperator, ParsedPopulate, ParsedQuery, ParsedSelect, ParsedSort, ParsedSortDirection, QueryParserInput, QueryParserOptions } from "./types.mjs";
+import { FilterOperator, FilterTerm, FormatQueryInput, QueryParams, formatQuery, stringifyQuery } from "./format-query.mjs";
 import { CORE_OPERATORS, CoreOperator, DEFAULT_LIMIT, DEFAULT_MAX_LIMIT, DEFAULT_MAX_SEARCH_LENGTH, DEFAULT_MAX_TEXT_LENGTH, ExtensionClause, FilterClause, FilterReadResult, OPERATOR_DESCRIPTIONS, PageOptions, PageRequest, QueryGrammarOptions, QueryInput, URL_OPERATORS, clausesToFilter, readFilterClauses, readPageRequest, readSearch, readSelect, readSort, toRecord } from "./grammar.mjs";
 import { parseUrl } from "./parse-url.mjs";
 import { MAX_UNBOUNDED_QUANTIFIERS, RegexRisk, assessRegex, escapeRegex } from "./regex-safety.mjs";
 import { STANDARD_RESERVED_PARAMS, isControlParam } from "./reserved.mjs";
-export { type BracketOperator, CORE_OPERATORS, type CoerceOptions, type CoreOperator, DEFAULT_LIMIT, DEFAULT_MAX_LIMIT, DEFAULT_MAX_SEARCH_LENGTH, DEFAULT_MAX_TEXT_LENGTH, type ExtensionClause, type FilterClause, type FilterReadResult, INVALID_QUERY_INPUT, MAX_UNBOUNDED_QUANTIFIERS, OPERATOR_DESCRIPTIONS, type PageOptions, type PageRequest, type ParsedPopulate, type ParsedQuery, type ParsedSelect, type ParsedSort, type ParsedSortDirection, type QueryErrorKind, type QueryFieldType, QueryGrammarError, type QueryGrammarOptions, type QueryInput, type QueryParserInput, type QueryParserOptions, type QueryScalar, type RegexRisk, STANDARD_RESERVED_PARAMS, URL_OPERATORS, assessRegex, clausesToFilter, coerceQueryValue, escapeRegex, isControlParam, isQueryGrammarError, parseUrl, readFilterClauses, readPageRequest, readSearch, readSelect, readSort, toRecord };
+export { type BracketOperator, CORE_OPERATORS, type CoerceOptions, type CoreOperator, DEFAULT_LIMIT, DEFAULT_MAX_LIMIT, DEFAULT_MAX_SEARCH_LENGTH, DEFAULT_MAX_TEXT_LENGTH, type ExtensionClause, type FilterClause, type FilterOperator, type FilterReadResult, type FilterTerm, type FormatQueryInput, INVALID_QUERY_INPUT, MAX_UNBOUNDED_QUANTIFIERS, OPERATOR_DESCRIPTIONS, type PageOptions, type PageRequest, type ParsedPopulate, type ParsedQuery, type ParsedSelect, type ParsedSort, type ParsedSortDirection, type QueryErrorKind, type QueryFieldType, QueryGrammarError, type QueryGrammarOptions, type QueryInput, type QueryParams, type QueryParserInput, type QueryParserOptions, type QueryScalar, type RegexRisk, STANDARD_RESERVED_PARAMS, URL_OPERATORS, assessRegex, clausesToFilter, coerceQueryValue, escapeRegex, formatQuery, isControlParam, isQueryGrammarError, parseUrl, readFilterClauses, readPageRequest, readSearch, readSelect, readSort, stringifyQuery, toRecord };

package/dist/query-parser/index.mjs

@@ -3,5 +3,6 @@ import { coerceQueryValue } from "./coerce.mjs";
 import { MAX_UNBOUNDED_QUANTIFIERS, assessRegex, escapeRegex } from "./regex-safety.mjs";
 import { STANDARD_RESERVED_PARAMS, isControlParam } from "./reserved.mjs";
 import { CORE_OPERATORS, DEFAULT_LIMIT, DEFAULT_MAX_LIMIT, DEFAULT_MAX_SEARCH_LENGTH, DEFAULT_MAX_TEXT_LENGTH, OPERATOR_DESCRIPTIONS, URL_OPERATORS, clausesToFilter, readFilterClauses, readPageRequest, readSearch, readSelect, readSort, toRecord } from "./grammar.mjs";
+import { formatQuery, stringifyQuery } from "./format-query.mjs";
 import { parseUrl } from "./parse-url.mjs";
-export { CORE_OPERATORS, DEFAULT_LIMIT, DEFAULT_MAX_LIMIT, DEFAULT_MAX_SEARCH_LENGTH, DEFAULT_MAX_TEXT_LENGTH, INVALID_QUERY_INPUT, MAX_UNBOUNDED_QUANTIFIERS, OPERATOR_DESCRIPTIONS, QueryGrammarError, STANDARD_RESERVED_PARAMS, URL_OPERATORS, assessRegex, clausesToFilter, coerceQueryValue, escapeRegex, isControlParam, isQueryGrammarError, parseUrl, readFilterClauses, readPageRequest, readSearch, readSelect, readSort, toRecord };
+export { CORE_OPERATORS, DEFAULT_LIMIT, DEFAULT_MAX_LIMIT, DEFAULT_MAX_SEARCH_LENGTH, DEFAULT_MAX_TEXT_LENGTH, INVALID_QUERY_INPUT, MAX_UNBOUNDED_QUANTIFIERS, OPERATOR_DESCRIPTIONS, QueryGrammarError, STANDARD_RESERVED_PARAMS, URL_OPERATORS, assessRegex, clausesToFilter, coerceQueryValue, escapeRegex, formatQuery, isControlParam, isQueryGrammarError, parseUrl, readFilterClauses, readPageRequest, readSearch, readSelect, readSort, stringifyQuery, toRecord };

package/dist/query-parser/parse-url.d.mts

@@ -1,6 +1,4 @@
 import { ParsedQuery, QueryParserInput, QueryParserOptions } from "./types.mjs";
-//#region src/query-parser/parse-url.d.ts
 /** Parse URL search params into a driver-agnostic ParsedQuery. Invalid input throws a 400. */
 declare function parseUrl(input: QueryParserInput, options?: QueryParserOptions): ParsedQuery;
-//#endregion
 export { parseUrl };

package/dist/query-parser/parse-url.mjs

@@ -1,6 +1,6 @@
 import { QueryGrammarError } from "./errors.mjs";
 import { clausesToFilter, readFilterClauses, readPageRequest, readSearch, readSelect, readSort, toRecord } from "./grammar.mjs";
-//#region src/query-parser/parse-url.ts
+// src/query-parser/parse-url.ts
 /**
 * URL → {@link ParsedQuery} with a portable Filter IR. The grammar (keys, operators, coercion,
 * paging) is `./grammar.ts`'s; this adds only the IR emission and the populate spec.
@@ -89,5 +89,4 @@ function readMatch(path, match) {
 	for (const [field, value] of Object.entries(match)) if (!FIELD_RE.test(field) || value !== null && typeof value === "object") throw new QueryGrammarError(`populate[${path}][match]`, `field equality only: "${field}"`, "syntax");
 	return match;
 }
-//#endregion
 export { parseUrl };

package/dist/query-parser/regex-safety.d.mts

@@ -1,4 +1,3 @@
-//#region src/query-parser/regex-safety.d.ts
 /**
  * ReDoS assessment for a user-supplied regex — the ONE analyser every parser uses.
  *
@@ -27,5 +26,4 @@ declare function assessRegex(pattern: string, options?: {
 }): RegexRisk;
 /** Escape every regex metacharacter — the literal-match fallback for an unsafe pattern. */
 declare function escapeRegex(value: string): string;
-//#endregion
 export { MAX_UNBOUNDED_QUANTIFIERS, RegexRisk, assessRegex, escapeRegex };

package/dist/query-parser/regex-safety.mjs

@@ -1,4 +1,4 @@
-//#region src/query-parser/regex-safety.ts
+// src/query-parser/regex-safety.ts
 /**
 * ReDoS assessment for a user-supplied regex — the ONE analyser every parser uses.
 *
@@ -147,5 +147,4 @@ function assessRegex(pattern, options = {}) {
 function escapeRegex(value) {
 	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
-//#endregion
 export { MAX_UNBOUNDED_QUANTIFIERS, assessRegex, escapeRegex };

package/dist/query-parser/reserved.d.mts

@@ -1,4 +1,3 @@
-//#region src/query-parser/reserved.d.ts
 /**
  * URL parameter keys reserved by the framework — never parsed as
  * filter predicates. Two categories:
@@ -39,5 +38,4 @@ declare const STANDARD_RESERVED_PARAMS: ReadonlySet<string>;
  * ```
  */
 declare function isControlParam(key: string): boolean;
-//#endregion
 export { STANDARD_RESERVED_PARAMS, isControlParam };

package/dist/query-parser/reserved.mjs

@@ -1,4 +1,4 @@
-//#region src/query-parser/reserved.ts
+// src/query-parser/reserved.ts
 /**
 * URL parameter keys reserved by the framework — never parsed as
 * filter predicates. Two categories:
@@ -55,5 +55,4 @@ const STANDARD_RESERVED_PARAMS = /* @__PURE__ */ new Set([
 function isControlParam(key) {
 	return STANDARD_RESERVED_PARAMS.has(key);
 }
-//#endregion
 export { STANDARD_RESERVED_PARAMS, isControlParam };

package/dist/query-parser/types.d.mts

@@ -1,6 +1,5 @@
 import { Filter } from "../filter/types.mjs";
 import { QueryFieldType } from "./coerce.mjs";
-//#region src/query-parser/types.d.ts
 /** Sort direction on a single field. */
 type ParsedSortDirection = 1 | -1;
 /** Sort spec after parsing — array so field order is preserved. */
@@ -89,5 +88,4 @@ type BracketOperator = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'nin'
  * or a compatible iterable. The parser normalizes.
  */
 type QueryParserInput = URLSearchParams | Record<string, string | string[] | undefined> | Iterable<[string, string]>;
-//#endregion
 export { BracketOperator, ParsedPopulate, ParsedQuery, ParsedSelect, ParsedSort, ParsedSortDirection, QueryParserInput, QueryParserOptions };

package/dist/repository/agg-output.d.mts

@@ -1,4 +1,3 @@
-//#region src/repository/agg-output.d.ts
 /**
  * Cross-kit AggResult row-shape normalization.
  *
@@ -59,5 +58,4 @@ declare function nestDottedKeys<T extends Record<string, unknown>>(row: T): Reco
  * normalized rows; the input is not modified.
  */
 declare function nestDottedKeysAll<T extends Record<string, unknown>>(rows: readonly T[]): Record<string, unknown>[];
-//#endregion
 export { nestDottedKeys, nestDottedKeysAll };

package/dist/repository/agg-output.mjs

@@ -1,4 +1,4 @@
-//#region src/repository/agg-output.ts
+// src/repository/agg-output.ts
 /**
 * Cross-kit AggResult row-shape normalization.
 *
@@ -85,5 +85,4 @@ function setDeep(target, path, value) {
 	}
 	cursor[path[path.length - 1]] = value;
 }
-//#endregion
 export { nestDottedKeys, nestDottedKeysAll };

package/dist/repository/archive.d.mts

@@ -1,5 +1,4 @@
 import { RetryPolicy } from "./resilience.mjs";
-//#region src/repository/archive.d.ts
 /**
  * Destination for archived documents — implemented by the HOST, not the
  * kit. One method so anything writable fits: an archive collection/table,
@@ -102,5 +101,4 @@ interface ArchiveResult {
  * @param port    Kit-specific driver glue (readChunk / deleteChunk).
  */
 declare function runChunkedArchive<TDoc = unknown>(options: ArchiveOptions, sink: ArchiveSink<TDoc>, port: ArchivePort<TDoc>): Promise<ArchiveResult>;
-//#endregion
 export { ArchiveOptions, ArchivePort, ArchiveProgress, ArchiveResult, ArchiveSink, runChunkedArchive };

package/dist/repository/archive.mjs

@@ -1,5 +1,5 @@
 import { withRetry } from "./resilience.mjs";
-//#region src/repository/archive.ts
+// src/repository/archive.ts
 /**
 * Drive a chunked archive to completion. Returns an `ArchiveResult`
 * envelope — never throws for in-run errors (those wrap into
@@ -60,5 +60,4 @@ async function runChunkedArchive(options, sink, port) {
 		durationMs: Date.now() - start
 	};
 }
-//#endregion
 export { runChunkedArchive };

package/dist/repository/base.d.mts

@@ -4,7 +4,6 @@ import { HookListener, HookMode } from "../hooks/types.mjs";
 import { HookEngine } from "../hooks/engine.mjs";
 import { StandardSchemaV1 } from "../schema/standard-schema.mjs";
 import { PluginType } from "./plugin-types.mjs";
-//#region src/repository/base.d.ts
 /** Construction options common to every kit. */
 interface RepositoryBaseOptions {
   /** Stable identifier (model/table name) — surfaces in hook contexts and ordering errors. */
@@ -117,5 +116,4 @@ declare abstract class RepositoryBase {
    */
   _cachedValue<T>(context: RepositoryContext): T | undefined;
 }
-//#endregion
 export { RepositoryBase, RepositoryBaseOptions };

package/dist/repository/base.mjs

@@ -3,7 +3,7 @@ import { HOOK_PRIORITY } from "../hooks/priority.mjs";
 import { registerRepositoryEvents } from "../events/emit.mjs";
 import { validateStandardSchema } from "../schema/standard-schema.mjs";
 import { validatePluginOrder } from "./plugin-types.mjs";
-//#region src/repository/base.ts
+// src/repository/base.ts
 /**
 * Base class every driver kit extends. Exposes the hook surface
 * (`on` / `off` / `emit` / `emitAsync`), plugin installation (`use`), and
@@ -153,5 +153,4 @@ function assertValidPlugin(plugin, repoName, index) {
 	}
 	if (typeof plugin.apply !== "function") throw new TypeError(`[repo-core] Repository "${repoName}": ${where} is an object but missing \`apply(repo)\`. Expected \`{ name: string, apply: (repo) => void }\`.`);
 }
-//#endregion
 export { RepositoryBase };

package/dist/repository/bulk-upsert.d.mts

@@ -1,5 +1,4 @@
 import { WriteOptions } from "./types.mjs";
-//#region src/repository/bulk-upsert.d.ts
 type BulkUpsertOutcome = 'inserted' | 'updated' | 'unchanged' | 'failed';
 declare const BULK_UPSERT_FAILURE_CODES: {
   /** A unique index other than (or racing on) the key refused the row. */
@@ -55,5 +54,4 @@ interface BulkUpsertResult {
 declare function bulkUpsertOptionsError(options: BulkUpsertOptions): string | undefined;
 /** Tally a positional result list into the summary counts. */
 declare function summarizeBulkUpsert(results: readonly BulkUpsertRowResult[]): BulkUpsertResult;
-//#endregion
 export { BULK_UPSERT_ERROR_CODES, BULK_UPSERT_FAILURE_CODES, BulkUpsertFailureCode, BulkUpsertOptions, BulkUpsertOutcome, BulkUpsertResult, BulkUpsertRowResult, bulkUpsertOptionsError, summarizeBulkUpsert };

package/dist/repository/bulk-upsert.mjs

@@ -1,4 +1,4 @@
-//#region src/repository/bulk-upsert.ts
+// src/repository/bulk-upsert.ts
 const BULK_UPSERT_FAILURE_CODES = {
 	/** A unique index other than (or racing on) the key refused the row. */
 	DUPLICATE: "duplicate",
@@ -46,5 +46,4 @@ function summarizeBulkUpsert(results) {
 	for (const r of results) out[r.outcome] += 1;
 	return out;
 }
-//#endregion
 export { BULK_UPSERT_ERROR_CODES, BULK_UPSERT_FAILURE_CODES, bulkUpsertOptionsError, summarizeBulkUpsert };

package/dist/repository/capabilities.d.mts

@@ -1,4 +1,3 @@
-//#region src/repository/capabilities.d.ts
 /**
  * Runtime capability descriptor — the feature-detection contract every
  * kit declares so hosts (and arc) can branch on backend support at boot
@@ -244,5 +243,4 @@ interface RepoCapabilities {
   /** Kit sources compose with `mergeKeysetPages` (scope-bound per-row cursors). Gates `runMergeKeysetConformance`. */
   mergeKeyset?: boolean;
 }
-//#endregion
 export { AggregateOpsSupport, RepoCapabilities };

package/dist/repository/distribution.d.mts

@@ -1,5 +1,4 @@
 import { FilterInput } from "./types.mjs";
-//#region src/repository/distribution.d.ts
 /** Per-repo declaration of how the underlying table/collection is distributed. */
 interface DistributionConfig {
   /**
@@ -43,5 +42,4 @@ type DistributionMissHandler = (info: {
  * once per operation name per guard instance to keep logs readable.
  */
 declare function createDistributionGuard(config: DistributionConfig, onMiss?: DistributionMissHandler): (operation: string, filter: FilterInput | undefined) => void;
-//#endregion
 export { DistributionConfig, DistributionMissHandler, createDistributionGuard, filterReferencesKey };

package/dist/repository/distribution.mjs

@@ -1,6 +1,6 @@
 import { isFilter } from "../filter/guard.mjs";
 import { collectFields } from "../filter/walk.mjs";
-//#region src/repository/distribution.ts
+// src/repository/distribution.ts
 /**
 * Distribution-key awareness — the lean, industry-standard slice of
 * "sharding support" that belongs in an access layer.
@@ -69,5 +69,4 @@ function createDistributionGuard(config, onMiss) {
 		}
 	};
 }
-//#endregion
 export { createDistributionGuard, filterReferencesKey };

package/dist/repository/options.d.mts

@@ -1,4 +1,3 @@
-//#region src/repository/options.d.ts
 /**
  * Canonical option keys forwarded into every `MinimalRepo` /
  * `StandardRepo` method call.
@@ -62,5 +61,4 @@ declare const STANDARD_REPO_OPTION_KEYS: readonly ['organizationId', 'userId', '
  * ```
  */
 type StandardRepoOptionKey = (typeof STANDARD_REPO_OPTION_KEYS)[number];
-//#endregion
 export { STANDARD_REPO_OPTION_KEYS, StandardRepoOptionKey };

package/dist/repository/options.mjs

@@ -1,4 +1,4 @@
-//#region src/repository/options.ts
+// src/repository/options.ts
 /**
 * Canonical option keys forwarded into every `MinimalRepo` /
 * `StandardRepo` method call.
@@ -58,5 +58,4 @@ const STANDARD_REPO_OPTION_KEYS = [
 	"requestId",
 	"traceId"
 ];
-//#endregion
 export { STANDARD_REPO_OPTION_KEYS };

package/dist/repository/plugin-types.d.mts

@@ -1,5 +1,4 @@
 import { RepositoryBase } from "./base.mjs";
-//#region src/repository/plugin-types.d.ts
 /** Object-style plugin — preferred form. Carries a stable `name` for ordering checks. */
 interface Plugin<TRepo extends RepositoryBase = RepositoryBase> {
   /** Stable identifier used by plugin-order validators. */
@@ -22,5 +21,4 @@ declare const PLUGIN_ORDER_CONSTRAINTS: readonly (readonly [string, string, stri
  * mode. Plain-function plugins (no `name`) are skipped — no false positives.
  */
 declare function validatePluginOrder(plugins: readonly PluginType[], repoName: string, mode?: 'warn' | 'throw' | 'off', onWarn?: (message: string) => void): void;
-//#endregion
 export { PLUGIN_ORDER_CONSTRAINTS, Plugin, PluginFunction, PluginType, validatePluginOrder };

package/dist/repository/plugin-types.mjs

@@ -1,4 +1,4 @@
-//#region src/repository/plugin-types.ts
+// src/repository/plugin-types.ts
 /**
 * Ordered pairs that produce wrong behavior when installed out of order.
 * Each entry: `[mustComeFirst, mustComeAfter, reason]`.
@@ -41,5 +41,4 @@ function validatePluginOrder(plugins, repoName, mode = "warn", onWarn = (m) => {
 		onWarn(message);
 	}
 }
-//#endregion
 export { PLUGIN_ORDER_CONSTRAINTS, validatePluginOrder };