@classytic/repo-core 0.28.0 → 0.30.0

package/dist/idempotency/index.mjs

@@ -0,0 +1,419 @@
+import { contentHash } from "../hash/index.mjs";
+//#region src/idempotency/index.ts
+/**
+* Idempotency — the ONE contract for "run this command at most once per key".
+*
+* **To make a command idempotent, call {@link runIdempotent} with an
+* {@link IdempotencyClaimStore}.** Never hand-roll a "done" flag, a unique index
+* checked after the side effect, or a per-module claims table: each of those
+* has shipped here, and each double-applied or blocked on a crash without
+* erroring.
+*
+* | layer | owns |
+* |---|---|
+* | this module | identity, fingerprint, lease, the decision, the store PORT, the runner |
+* | a persistence kit (`mongokit`, …) | a store — must pass `runIdempotencyStoreConformance` (`./testing`) |
+* | arc | HTTP: the header, required keys, response replay |
+* | a kernel / spine module | the operation name and scope (`pos.checkout`, `{ organizationId }`) |
+*
+* Lives in repo-core for the reason `./lock` does: the store contract is driver-free — any
+* store with a unique key and a conditional update implements it — and every kit already
+* depends on this package.
+*
+* ## The three-valued outcome is the point
+*
+* {@link ClaimOutcome} is `claimed | replayed | in_flight`, and **`in_flight` is
+* not a failure.** A concurrent attempt holding a live lease means the answer is
+* *not yet known*, exactly like a provider timeout: the work may be about to
+* succeed. Mapping it onto an error licenses the caller to retry the mutation,
+* and if the first attempt lands that is a double-apply — the same asymmetry
+* that makes `unknown` a required payment outcome. The correct handling is to
+* wait out {@link InFlightDecision.retryAfterMs} and ask again, never to
+* re-execute.
+*
+* ## Two identifiers that must not be confused
+*
+* - **`key`** — caller-supplied, STABLE across retries of one logical command.
+*   Derive it deterministically; a random fallback defeats deduplication while
+*   looking correctly wired.
+* - **`leaseToken`** — minted fresh per ATTEMPT, and deliberately random. It
+*   answers "am I still the attempt that owns this claim?", so two attempts
+*   must never mint the same one. Deriving it would make a takeover
+*   indistinguishable from the attempt it replaced.
+*/
+/** Deepest body {@link fingerprintRequest} accepts — MongoDB's own document limit. */
+const MAX_FINGERPRINT_DEPTH = 100;
+/** Default crash-window lease, matching `@classytic/cart`'s proven 30s. */
+const DEFAULT_LEASE_MS = 3e4;
+var IdempotencyError = class extends Error {
+	name = "IdempotencyError";
+	code;
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+	}
+};
+/**
+* The deterministic string form of an identity — the unique key a store indexes.
+*
+* JSON of `[operation, key, [[scopeKey, value], …]]` with scope keys in CODE-POINT order.
+* Never a delimiter join (`{ ref: 'a:b' }` and `{ ref: 'a', x: 'b' }` would collide) and
+* never a locale-aware sort: a key that moves when a server's locale changes lets a retry miss
+* its claim and execute again.
+*/
+function identityKey(identity) {
+	assertNonEmpty(identity.operation, "identity.operation");
+	assertNonEmpty(identity.key, "identity.key");
+	const scope = identity.scope ?? {};
+	const pairs = Object.keys(scope).sort().map((k) => [k, scope[k]]);
+	return JSON.stringify([
+		identity.operation,
+		identity.key,
+		pairs
+	]);
+}
+/** True when two identities address the same claim. */
+function sameIdentity(a, b) {
+	return identityKey(a) === identityKey(b);
+}
+/**
+* Fingerprint a request body — the canonical digest of what the WIRE carries.
+*
+* Key-order independent, and wire-equivalent: an `undefined` property is absent, a `Date`
+* is its ISO string, an object is its `toJSON` — so a body a caller built in memory
+* fingerprints like the same body received over HTTP. Use the WHOLE body that decides the
+* mutation; a subset lets two different commands share a fingerprint.
+*
+* Throws `UNFINGERPRINTABLE` past {@link MAX_FINGERPRINT_DEPTH} levels — refuse that body.
+*/
+function fingerprintRequest(body) {
+	return contentHash(toWire(body === void 0 ? null : body, 0));
+}
+/** JSON's projection (`undefined` dropped / `null` in arrays, `toJSON` honoured), depth-bounded. */
+function toWire(value, depth) {
+	if (value === null || typeof value !== "object") return value;
+	if (depth >= 100) throw new IdempotencyError("UNFINGERPRINTABLE", `request body nested deeper than 100 levels`);
+	const json = value.toJSON;
+	if (typeof json === "function") return toWire(json.call(value), depth);
+	if (Array.isArray(value)) return value.map((v) => v === void 0 ? null : toWire(v, depth + 1));
+	const out = {};
+	for (const [k, v] of Object.entries(value)) if (v !== void 0) out[k] = toWire(v, depth + 1);
+	return out;
+}
+/**
+* Mint a lease token for ONE attempt.
+*
+* Random on purpose — see the module docblock. This is the one identifier in
+* the idempotency contract that must NOT be derived.
+*/
+function newLeaseToken() {
+	const c = globalThis.crypto;
+	if (typeof c?.randomUUID === "function") return c.randomUUID();
+	return `lease_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 12)}`;
+}
+/** Has the crash-window lease lapsed at `now`? Expiry is exclusive of `now`. */
+function isLeaseExpired(claim, now) {
+	return now.getTime() >= claim.leaseExpiresAt.getTime();
+}
+/** Does `leaseToken` still own this claim at `now`? */
+function holdsLease(claim, leaseToken, now) {
+	return claim.leaseToken === leaseToken && !isLeaseExpired(claim, now);
+}
+/**
+* The whole state machine, as one pure function.
+*
+* | stored state | lease | decision |
+* |---|---|---|
+* | (none) | — | `claimed` — fresh claim |
+* | `in_flight` | live | `in_flight` — wait, do NOT execute |
+* | `in_flight` | lapsed | `claimed` — takeover, `tookOverFrom` set |
+* | `in_flight` | lapsed, `attempts ≥ maxAttempts` | `exhausted` — escalate, do NOT execute |
+* | `succeeded` / `failed` | — | `replayed` — return the stored result |
+*
+* Two conditions throw rather than returning a decision, because both mean the
+* question itself was wrong:
+*
+* - **`FINGERPRINT_MISMATCH`** — the same key with a different body. That is
+*   two commands, not one retried command; answering either way is wrong.
+*   Surface it as a 4xx (Stripe returns 400 here), never as a fresh claim.
+* - **`MISSING_REPLAY`** — a terminal record with no stored result. There is
+*   nothing to replay, and inventing an empty success is precisely the silent
+*   permissive default this codebase keeps getting bitten by.
+*/
+function decideClaim(existing, request) {
+	assertNonEmpty(request.requestFingerprint, "request.requestFingerprint");
+	assertNonEmpty(request.leaseToken, "request.leaseToken");
+	assertInstant(request.now, "request.now");
+	const leaseMs = request.leaseMs ?? 3e4;
+	if (!Number.isFinite(leaseMs) || leaseMs <= 0) throw new IdempotencyError("INVALID_CLAIM", `leaseMs must be a positive number of milliseconds, got ${String(request.leaseMs)} — a zero or negative lease is instantly expired, so every concurrent attempt takes over and executes.`);
+	if (existing == null) return {
+		outcome: "claimed",
+		claim: mintClaim(request, leaseMs, 1)
+	};
+	if (existing.requestFingerprint !== request.requestFingerprint) throw new IdempotencyError("FINGERPRINT_MISMATCH", `Idempotency key '${existing.identity.key}' was first used with a different request body (stored ${existing.requestFingerprint.slice(0, 12)}…, presented ${request.requestFingerprint.slice(0, 12)}…). Two distinct commands are sharing one key — replaying the first would return the wrong result, and claiming afresh would apply the second under a key already spent.`);
+	if (existing.state === "succeeded" || existing.state === "failed") {
+		if (existing.result === void 0) throw new IdempotencyError("MISSING_REPLAY", `Claim '${existing.identity.key}' is terminal (${existing.state}) but stores no result, so the retry cannot be answered. Reporting success here would fabricate an outcome that was never observed.`);
+		return {
+			outcome: "replayed",
+			claim: existing,
+			result: existing.result
+		};
+	}
+	if (!isLeaseExpired(existing, request.now)) return {
+		outcome: "in_flight",
+		claim: existing,
+		retryAfterMs: existing.leaseExpiresAt.getTime() - request.now.getTime()
+	};
+	if (request.maxAttempts !== void 0 && existing.attempts >= request.maxAttempts) return {
+		outcome: "exhausted",
+		claim: existing
+	};
+	return {
+		outcome: "claimed",
+		claim: {
+			...mintClaim(withoutContext(request), leaseMs, existing.attempts + 1),
+			createdAt: existing.createdAt,
+			...existing.progress !== void 0 ? { progress: existing.progress } : {},
+			...existing.context !== void 0 ? { context: existing.context } : {},
+			...existing.lastError !== void 0 ? { lastError: existing.lastError } : {}
+		},
+		tookOverFrom: existing.leaseToken
+	};
+}
+/** A takeover keeps the FIRST attempt's context, so the new request's is dropped. */
+function withoutContext(request) {
+	const { context: _ignored, ...rest } = request;
+	return rest;
+}
+function mintClaim(request, leaseMs, attempts) {
+	identityKey(request.identity);
+	return {
+		identity: request.identity,
+		requestFingerprint: request.requestFingerprint,
+		state: "in_flight",
+		leaseToken: request.leaseToken,
+		leaseExpiresAt: new Date(request.now.getTime() + leaseMs),
+		createdAt: request.now,
+		...request.context !== void 0 ? { context: request.context } : {},
+		attempts
+	};
+}
+/**
+* Extend a live lease — for a command that legitimately outruns the crash
+* window. Throws `LEASE_LOST` when the caller no longer owns the claim, so a
+* superseded attempt cannot silently keep working and then write its result
+* over the winner's.
+*/
+function renewLease(claim, input) {
+	assertInstant(input.now, "now");
+	if (claim.state !== "in_flight") throw new IdempotencyError("ALREADY_TERMINAL", `cannot renew a ${claim.state} claim`);
+	if (!holdsLease(claim, input.leaseToken, input.now)) throw new IdempotencyError("LEASE_LOST", `lease token does not own this claim at ${input.now.toISOString()} (expired or taken over) — continuing would let two attempts believe they are the live one.`);
+	return {
+		...claim,
+		leaseExpiresAt: new Date(input.now.getTime() + (input.leaseMs ?? 3e4))
+	};
+}
+/**
+* Move a claim to a terminal state with the result retries will replay.
+*
+* The lease check is the important part: an attempt whose lease lapsed and was
+* taken over must NOT write its result. Without it, the slow attempt's answer
+* overwrites the takeover's, and every subsequent retry replays an outcome that
+* does not match what was actually applied.
+*/
+function completeClaim(claim, input) {
+	assertInstant(input.now, "now");
+	if (claim.state !== "in_flight") throw new IdempotencyError("ALREADY_TERMINAL", `claim is already ${claim.state}; completing it again would replace a result that retries may already have replayed.`);
+	if (claim.leaseToken !== input.leaseToken) throw new IdempotencyError("LEASE_LOST", "lease token does not own this claim — another attempt took it over, and writing this result would overwrite theirs.");
+	return {
+		...claim,
+		state: input.result.status,
+		result: input.result,
+		completedAt: input.now
+	};
+}
+/**
+* Narrowing helper for the one outcome callers keep getting wrong.
+*
+* `in_flight` is neither success nor failure. Route it to a 409 + `Retry-After`
+* (or an internal wait), never to the command's error path.
+*/
+function isInFlight(decision) {
+	return decision.outcome === "in_flight";
+}
+/**
+* A replay of a command that failed TERMINALLY — the same answer the first
+* attempt got. `code` / `status` are the stored {@link ClaimError}.
+*/
+var IdempotentReplayError = class extends Error {
+	name = "IdempotentReplayError";
+	code;
+	status;
+	constructor(error) {
+		super(error.message);
+		this.code = error.code;
+		if (error.status !== void 0) this.status = error.status;
+	}
+};
+/** Bounded so a store that never lets an insert or swap win cannot spin forever. */
+const MAX_CLAIM_ROUNDS = 5;
+/**
+* Run `execute` at most once per identity: claim → execute → complete.
+*
+* - a first attempt, or a takeover of a lapsed lease → executes (a takeover resumes from
+*   the stored progress and context);
+* - a completed success → replays the stored value;
+* - a completed terminal failure → throws {@link IdempotentReplayError};
+* - a live attempt elsewhere → `in_flight`, never an execution;
+* - a lapsed claim past `maxAttempts` → `exhausted`, never an execution;
+* - the same key with a different body → throws `FINGERPRINT_MISMATCH`.
+*
+* A failure of `execute` is rethrown unchanged after the claim is updated per its
+* {@link FailureDisposition}. A completion that finds the lease taken over throws
+* `LEASE_LOST`: the work WAS applied, so saying "ok" would hide that two attempts ran.
+*/
+async function runIdempotent(options) {
+	const { store, identity, requestFingerprint, storeOptions } = options;
+	const now = options.now ?? (() => /* @__PURE__ */ new Date());
+	const mintToken = options.newLeaseToken ?? newLeaseToken;
+	let claim;
+	for (let round = 0; round < MAX_CLAIM_ROUNDS && !claim; round++) {
+		const decision = decideClaim(await store.get(identity, storeOptions), {
+			identity,
+			requestFingerprint,
+			now: now(),
+			leaseToken: mintToken(),
+			...options.leaseMs !== void 0 ? { leaseMs: options.leaseMs } : {},
+			...options.context !== void 0 ? { context: options.context } : {},
+			...options.maxAttempts !== void 0 ? { maxAttempts: options.maxAttempts } : {}
+		});
+		if (decision.outcome === "in_flight") return {
+			outcome: "in_flight",
+			retryAfterMs: decision.retryAfterMs,
+			progress: decision.claim.progress
+		};
+		if (decision.outcome === "exhausted") return {
+			outcome: "exhausted",
+			attempts: decision.claim.attempts,
+			progress: decision.claim.progress,
+			lastError: decision.claim.lastError
+		};
+		if (decision.outcome === "replayed") {
+			if (decision.result.status === "failed") throw new IdempotentReplayError(decision.result.error);
+			return {
+				outcome: "replayed",
+				value: decision.result.value
+			};
+		}
+		if (decision.tookOverFrom === void 0 ? await store.insert(decision.claim, storeOptions) : await store.swap(identity, decision.tookOverFrom, decision.claim, storeOptions)) claim = decision.claim;
+	}
+	if (!claim) throw new IdempotencyError("INVALID_CLAIM", `could not claim '${identity.key}' in ${MAX_CLAIM_ROUNDS} rounds — the store keeps refusing both insert and swap, which a conforming store cannot do.`);
+	const { leaseToken } = claim;
+	let current = claim;
+	const checkpoint = async (progress, callOptions) => {
+		const next = {
+			...current,
+			progress: {
+				...current.progress,
+				...progress
+			}
+		};
+		if (!await store.swap(identity, leaseToken, next, callOptions ?? storeOptions)) throw new IdempotencyError("LEASE_LOST", `'${identity.key}' was taken over by another attempt — stop, the command is no longer this attempt's.`);
+		current = next;
+	};
+	let value;
+	try {
+		value = await options.execute({
+			leaseToken,
+			attempt: claim.attempts,
+			progress: claim.progress,
+			context: claim.context,
+			checkpoint
+		});
+	} catch (error) {
+		let disposition = options.classifyFailure?.(error) ?? { kind: "transient" };
+		if (disposition.kind === "transient" && current.progress !== void 0) disposition = { kind: "ambiguous" };
+		try {
+			if (disposition.kind === "terminal") {
+				const failed = completeClaim(current, {
+					leaseToken,
+					now: now(),
+					result: {
+						status: "failed",
+						error: disposition.error
+					}
+				});
+				await store.swap(identity, leaseToken, failed, storeOptions);
+			} else if (disposition.kind === "ambiguous") {
+				const lapsed = {
+					...current,
+					leaseExpiresAt: now(),
+					lastError: errorMessage(error)
+				};
+				await store.swap(identity, leaseToken, lapsed, storeOptions);
+			} else await store.release(identity, leaseToken, storeOptions);
+		} catch {}
+		throw error;
+	}
+	const done = completeClaim(current, {
+		leaseToken,
+		now: now(),
+		result: {
+			status: "succeeded",
+			value
+		}
+	});
+	if (!await store.swap(identity, leaseToken, done, storeOptions)) throw new IdempotencyError("LEASE_LOST", `'${identity.key}' executed, but its lease was taken over before it could complete — the command may have run twice. Raise leaseMs above the command's run time.`);
+	return {
+		outcome: "executed",
+		value,
+		attempt: claim.attempts
+	};
+}
+function errorMessage(error) {
+	return (error instanceof Error ? error.message : String(error)).slice(0, 500);
+}
+function assertNonEmpty(value, label) {
+	if (typeof value !== "string" || value.length === 0) throw new IdempotencyError("INVALID_CLAIM", `${label} must be a non-empty string, got ${String(value)}`);
+}
+function assertInstant(value, label) {
+	if (!(value instanceof Date) || !Number.isFinite(value.getTime())) throw new IdempotencyError("INVALID_CLAIM", `${label} must be a valid Date, got ${String(value)}`);
+}
+/**
+* In-memory {@link IdempotencyClaimStore} — tests, scripts, single-process tools. Not for a
+* server: claims die with the process, so a retry after a restart executes again.
+*/
+function createMemoryIdempotencyStore() {
+	const rows = /* @__PURE__ */ new Map();
+	const ownedInFlight = (identity, token) => {
+		const row = rows.get(identityKey(identity));
+		return row !== void 0 && row.state === "in_flight" && row.leaseToken === token;
+	};
+	return {
+		async get(identity) {
+			return rows.get(identityKey(identity)) ?? null;
+		},
+		async insert(claim) {
+			const key = identityKey(claim.identity);
+			if (rows.has(key)) return false;
+			rows.set(key, claim);
+			return true;
+		},
+		async swap(identity, expectedLeaseToken, next) {
+			if (!ownedInFlight(identity, expectedLeaseToken)) return false;
+			rows.set(identityKey(identity), next);
+			return true;
+		},
+		async release(identity, expectedLeaseToken) {
+			if (!ownedInFlight(identity, expectedLeaseToken)) return false;
+			rows.delete(identityKey(identity));
+			return true;
+		},
+		async listLapsed(operation, now, limit) {
+			return [...rows.values()].filter((c) => c.identity.operation === operation && c.state === "in_flight" && c.leaseExpiresAt <= now).sort((a, b) => a.leaseExpiresAt.getTime() - b.leaseExpiresAt.getTime()).slice(0, limit);
+		},
+		claims: () => [...rows.values()]
+	};
+}
+//#endregion
+export { DEFAULT_LEASE_MS, IdempotencyError, IdempotentReplayError, MAX_FINGERPRINT_DEPTH, completeClaim, createMemoryIdempotencyStore, decideClaim, fingerprintRequest, holdsLease, identityKey, isInFlight, isLeaseExpired, newLeaseToken, renewLease, runIdempotent, sameIdentity };

package/dist/pagination/types.d.mts

@@ -136,6 +136,12 @@ interface KeysetPaginationResultCore<TDoc> {
   prev?: string | null;
   /** Whether a previous page exists. Absent when the kit does not track it. */
   hasPrev?: boolean;
+  /**
+   * Cursor at this page's LAST row, whether or not more rows exist — feed it back as
+   * `after` to resume later (a change feed continues from its end, where `next` is null).
+   * `null` for an empty page. Absent when the kit does not mint it: treat as unknown.
+   */
+  end?: string | null;
 }
 /**
  * Keyset-paginated result envelope.

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

@@ -1,15 +1,22 @@
-import { QueryParserOptions } from "./types.mjs";
 //#region src/query-parser/coerce.d.ts
 /**
- * Coerce a single URL value to its field-declared type, or to a best-guess
- * scalar when no hint exists. Always returns `string`, `number`, `boolean`,
- * `Date`, or `null` — never `undefined`.
+ * 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
+ * digit string long enough to be an id or to lose precision, and a date only for a RANGE operand —
+ * `?code=2026-01-01` is a string far more often than a date.
  */
-declare function coerceValue(rawValue: string, fieldType: QueryParserOptions['fieldTypes'] extends (infer T) ? T extends Record<string, infer V> ? V | undefined : undefined : undefined): unknown;
-/**
- * Split a comma-separated URL value into an array of coerced scalars.
- * Used by `in`/`nin`/`between` which accept `field[in]=a,b,c`.
- */
-declare function coerceList(rawValue: string, fieldType: Parameters<typeof coerceValue>[1]): unknown[];
+/** Field types a caller (or a kit, from its schema) can declare for exact coercion. */
+type QueryFieldType = 'string' | 'number' | 'boolean' | 'date';
+/** What a URL value coerces to. */
+type QueryScalar = string | number | boolean | Date | null;
+interface CoerceOptions {
+  /** The field's declared type, when known. */
+  fieldType?: QueryFieldType | undefined;
+  /** True for a range operand (`gt`/`gte`/`lt`/`lte`/`between`) — enables date detection. */
+  range?: boolean;
+  /** The parameter, for the error message. */
+  param: string;
+}
+declare function coerceQueryValue(raw: string, options: CoerceOptions): QueryScalar;
 //#endregion
-export { coerceList, coerceValue };
+export { CoerceOptions, QueryFieldType, QueryScalar, coerceQueryValue };

package/dist/query-parser/coerce.mjs

@@ -1,80 +1,48 @@
 import { ISO_DATE_PATTERN } from "../filter/coerce-dates.mjs";
+import { QueryGrammarError } from "./errors.mjs";
 //#region src/query-parser/coerce.ts
 /**
-* Scalar coercion. URLs are strings; filters compare against typed fields.
-* The parser uses `fieldTypes` hints when provided, otherwise a safe
-* heuristic that avoids the classic footguns (string SKUs becoming
-* numbers, numeric-looking strings becoming Dates).
+* 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
+* digit string long enough to be an id or to lose precision, and a date only for a RANGE operand —
+* `?code=2026-01-01` is a string far more often than a date.
 */
-const BOOLEAN_STRINGS = /* @__PURE__ */ new Set([
-	"true",
-	"1",
-	"yes",
-	"on"
-]);
-const FALSEY_STRINGS = /* @__PURE__ */ new Set([
-	"false",
-	"0",
-	"no",
-	"off"
-]);
-const ISO_DATE_RE = ISO_DATE_PATTERN;
-/**
-* Coerce a single URL value to its field-declared type, or to a best-guess
-* scalar when no hint exists. Always returns `string`, `number`, `boolean`,
-* `Date`, or `null` — never `undefined`.
-*/
-function coerceValue(rawValue, fieldType) {
-	if (rawValue === "null") return null;
+const HEURISTIC_NUMBER = /^-?(?:0|[1-9]\d*)(?:\.\d+)?$/;
+const MAX_HEURISTIC_NUMBER_LENGTH = 15;
+const STRICT_NUMBER = /^-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?$/;
+function coerceQueryValue(raw, options) {
+	if (raw === "null") return null;
+	const { fieldType, param } = options;
 	switch (fieldType) {
-		case "number": {
-			const n = Number(rawValue);
-			return Number.isFinite(n) ? n : rawValue;
-		}
-		case "boolean": return BOOLEAN_STRINGS.has(rawValue.toLowerCase());
-		case "date": {
-			const d = new Date(rawValue);
-			return Number.isNaN(d.getTime()) ? rawValue : d;
+		case "string": return raw;
+		case "number":
+			if (!STRICT_NUMBER.test(raw)) throw new QueryGrammarError(param, `"${raw}" is not a number`);
+			return Number(raw);
+		case "boolean": {
+			const lower = raw.toLowerCase();
+			if (lower === "true" || lower === "1") return true;
+			if (lower === "false" || lower === "0") return false;
+			throw new QueryGrammarError(param, `"${raw}" is not a boolean (true/false)`);
 		}
-		case "string": return rawValue;
-		default: return heuristicCoerce(rawValue);
+		case "date": return toDate(raw) ?? fail(param, `"${raw}" is not an ISO-8601 date`);
 	}
-}
-/**
-* Heuristic used when no field-type hint applies. Deliberately conservative:
-*
-* - Pure boolean strings ("true", "false") → boolean.
-* - Unambiguous ISO-8601 dates → Date.
-* - Integers that don't start with 0 (unless literal "0") → number.
-* - Floats → number.
-* - Anything else stays a string.
-*
-* We do NOT coerce arbitrary-looking numeric strings ("12345") because
-* they're routinely SKUs, order IDs, or phone numbers. Callers needing
-* reliable numeric coercion pass `fieldTypes: { age: 'number' }`.
-*/
-function heuristicCoerce(value) {
-	if (BOOLEAN_STRINGS.has(value) && value.length <= 5) {
-		if (value === "true" || value === "false") return value === "true";
+	if (raw === "true") return true;
+	if (raw === "false") return false;
+	if (options.range) {
+		const date = toDate(raw);
+		if (date) return date;
+		if (STRICT_NUMBER.test(raw) && Number.isFinite(Number(raw))) return Number(raw);
 	}
-	if (FALSEY_STRINGS.has(value) && (value === "false" || value === "true")) return value === "true";
-	if (ISO_DATE_RE.test(value)) {
-		const d = new Date(value);
-		if (!Number.isNaN(d.getTime())) return d;
-	}
-	if (/^-?\d+\.\d+$/.test(value)) {
-		const n = Number(value);
-		if (Number.isFinite(n)) return n;
-	}
-	return value;
+	if (raw.length <= MAX_HEURISTIC_NUMBER_LENGTH && HEURISTIC_NUMBER.test(raw)) return Number(raw);
+	return raw;
 }
-/**
-* Split a comma-separated URL value into an array of coerced scalars.
-* Used by `in`/`nin`/`between` which accept `field[in]=a,b,c`.
-*/
-function coerceList(rawValue, fieldType) {
-	if (rawValue.length === 0) return [];
-	return rawValue.split(",").map((v) => coerceValue(v.trim(), fieldType));
+function toDate(raw) {
+	if (!ISO_DATE_PATTERN.test(raw)) return void 0;
+	const date = new Date(raw);
+	return Number.isNaN(date.getTime()) ? void 0 : date;
+}
+function fail(param, reason) {
+	throw new QueryGrammarError(param, reason);
 }
 //#endregion
-export { coerceList, coerceValue };
+export { coerceQueryValue };

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

@@ -0,0 +1,30 @@
+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";
+/**
+ * What kind of input was refused — so a lenient parser can relax one kind without the others:
+ * - `syntax`: not query grammar at all (a `$` key, an unknown operator, malformed nesting) —
+ *   an operator-smuggling attempt looks like this, so it is never worth tolerating.
+ * - `policy`: well-formed but outside an allowlist (a field, operator or sort field).
+ * - `value`: a value that does not fit (a type, a bound, an unsafe regex, a length).
+ */
+type QueryErrorKind = 'syntax' | 'policy' | 'value';
+/**
+ * A list query the grammar refuses (400). `validationErrors[0].path` names the offending
+ * parameter, so a client can attach the message to the filter control that produced it.
+ */
+declare class QueryGrammarError extends Error implements HttpError {
+  readonly status = 400;
+  readonly code = "INVALID_QUERY_INPUT";
+  readonly meta: {
+    readonly param: string;
+    readonly reason: string;
+    readonly kind: QueryErrorKind;
+  };
+  readonly validationErrors: ValidationErrorMeta[];
+  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

@@ -0,0 +1,32 @@
+//#region src/query-parser/errors.ts
+/** The code every query-grammar refusal carries — stable across parsers and kits. */
+const INVALID_QUERY_INPUT = "INVALID_QUERY_INPUT";
+/**
+* A list query the grammar refuses (400). `validationErrors[0].path` names the offending
+* parameter, so a client can attach the message to the filter control that produced it.
+*/
+var QueryGrammarError = class extends Error {
+	status = 400;
+	code = INVALID_QUERY_INPUT;
+	meta;
+	validationErrors;
+	constructor(param, reason, kind = "value") {
+		super(`Invalid query parameter "${param}": ${reason}`);
+		this.name = "QueryGrammarError";
+		this.meta = {
+			param,
+			reason,
+			kind
+		};
+		this.validationErrors = [{
+			validator: "query",
+			error: reason,
+			path: param
+		}];
+	}
+};
+function isQueryGrammarError(value) {
+	return value instanceof Error && value.code === "INVALID_QUERY_INPUT";
+}
+//#endregion
+export { INVALID_QUERY_INPUT, QueryGrammarError, isQueryGrammarError };