@classytic/repo-core 0.17.0 → 0.19.0

package/CHANGELOG.md

@@ -4,6 +4,53 @@ All notable changes to `@classytic/repo-core` are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.19.0] - 2026-07-29
+
+### Added — `coerceFilterDates` + ISO date helpers (`./filter`)
+
+- **`coerceFilterDates(filter)`** — walks a record-shape filter (Mongo-dialect or bare bracket-op syntax) and coerces ISO-8601 strings on range operators (`gt`/`gte`/`lt`/`lte` and `$`-prefixed equivalents) to `Date`, recursing through `$and`/`$or`/`$nor`/`$not` logical wrappers. Returns a new object; the input is never mutated. Equality operators are deliberately excluded — a string that happens to look like a date is far more likely a string id than a date equality predicate. Fixes silent empty results on aggregation `$match` stages: MongoDB `$match` (unlike `find`) performs no schema casting, so a string compared to a Date column matches nothing.
+- **`tryCoerceIsoDate(value)`** — coerces one unknown value to a `Date` when it is an unambiguous ISO-8601 string; returns anything else untouched. Safe to apply unconditionally.
+- **`ISO_DATE_PATTERN`** — the single regex source of truth for tight ISO-8601 detection (date-only through millisecond precision + optional timezone). `query-parser/coerce.ts` now imports this instead of keeping a duplicate pattern — one definition means the URL boundary and the compile boundary can never disagree on what "looks like a date".
+
+All three are exported from `@classytic/repo-core/filter`. Purely additive.
+
+## [0.18.0] - 2026-07-27
+
+### Added — `definePurgeStep` builder (`./cleanup`) and `resolveTenantField` (`./tenant`)
+
+#### `./cleanup` — `definePurgeStep`
+
+- **`definePurgeStep(repository, spec)`** — standard builder for the most common
+  `CleanupStep` shape: a chunked `purgeByField` over a single scope value.
+  Nearly every provider step in a domain kernel is this pattern; the builder owns
+  the invariant core so callers only declare what differs:
+  - **fail-closed scoping** — missing scope value or unavailable repository is a
+    `BLOCKER` (not a silent no-op and never an unscoped purge that would hit every
+    tenant); blocked by `SCOPE_REQUIRED:<param>` / `REPOSITORY_UNAVAILABLE:<id>`.
+  - **cancellation** — `throwIfCancelled` is called before work starts and the
+    `signal` is threaded to the kit so a cancel lands between committed chunks.
+  - **honest failure** — a failing purge returns `ok: false` so the recipe composer
+    stops (retention §8); thrown errors are caught and reported, never swallowed.
+  - **verification** — absence is re-queried after the run via `countDocuments`
+    (`spec.verifyFilter` for steps whose match filter differs from the absence proof).
+- **`PurgeStepSpec`** — declaration object: `id`, `resource`, `parameter`, `field`,
+  `strategy`, optional `retained`, `warnings`, `batchSize`, `guard(scope, ctx)`,
+  `verifyFilter(scope)`, `verifyName`.
+- **`PurgeStepRepository`** — structural subset of `StandardRepo` satisfied by any
+  kit repository that implements `purgeByField` + `countDocuments`.
+- **`SCOPE_REQUIRED`** / **`REPOSITORY_UNAVAILABLE`** — blocker-code prefix constants.
+
+#### `./tenant` — `resolveTenantField`
+
+- **`resolveTenantField(config?)`** — returns the single `tenantField` string a
+  resource layer needs for `defineResource({ tenantField })`, or `false` when the
+  config disables tenant scoping (`false` / `{ enabled: false }` / `{ strategy: 'none' }`).
+  Four spine modules hand-rolled equivalent logic independently, each re-deriving
+  `'organizationId'` as the default; one copy omitted the disable branch, making
+  that package silently un-configurable. This function is the single definition.
+
+Both additions are purely additive — no breaking changes.
+
 ## [0.17.0] - 2026-07-25
 
 ### Added — `./cleanup`: framework-free cleanup provider step contract

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Classytic
+Copyright (c) 2026 Classytic LLC
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -239,3 +239,10 @@ See [docs/data-lifecycle.md](./docs/data-lifecycle.md) for the billion-row runbo
 ## License
 
 MIT — see [LICENSE](./LICENSE).
+
+
+## Trademark
+
+The code is MIT-licensed. **"Classytic", "arc", and the logos are trademarks of
+Classytic LLC** and are **not** licensed under MIT — see [TRADEMARK.md](TRADEMARK.md).
+Forks must be renamed; the license covers the code, not the brand.

package/dist/cleanup/define-purge-step.d.mts

@@ -0,0 +1,76 @@
+import { TenantPurgeOptions, TenantPurgeStrategy } from "../repository/types.mjs";
+import { CleanupStep, CleanupStepContext } from "./types.mjs";
+//#region src/cleanup/define-purge-step.d.ts
+/**
+ * The repository surface a purge step needs — a structural subset of
+ * `StandardRepo`, so any kit repository satisfies it without an adapter.
+ * Both members are optional so an engine that never wired the repository
+ * yields a BLOCKER rather than a crash.
+ */
+interface PurgeStepRepository {
+  purgeByField?(field: string, value: unknown, strategy: TenantPurgeStrategy, options?: TenantPurgeOptions): Promise<{
+    processed: number;
+    ok: boolean;
+    error?: {
+      message: string;
+    };
+  }>;
+  countDocuments?(filter: Record<string, unknown>): Promise<number>;
+}
+interface PurgeStepSpec {
+  /** Stable machine id, unique within a recipe. */
+  id: string;
+  /** Business record class for the preview (e.g. `'CRM contacts'`). */
+  resource: string;
+  /**
+   * Run-parameter key carrying the scope value (e.g. `'subjectId'`,
+   * `'organizationId'`). Read from `ctx.parameters` at plan AND execute time,
+   * so a retry replays the value the operator actually confirmed.
+   */
+  parameter: string;
+  /** Document field matched against the parameter's value. */
+  field: string;
+  /** What to do with matched rows. */
+  strategy: TenantPurgeStrategy;
+  /** What survives — surfaced in the preview. */
+  retained?: string;
+  /** Non-blocking operator warnings. */
+  warnings?: readonly string[];
+  /** Rows per chunk. Kit default when omitted. */
+  batchSize?: number;
+  /**
+   * Domain blockers beyond the built-in scope/availability checks (e.g.
+   * `'OPEN_CHECKOUTS:3'`). A non-empty result is a HARD STOP.
+   */
+  guard?: (scope: string, ctx: CleanupStepContext) => Promise<readonly string[]>;
+  /**
+   * Filter proving absence, when it differs from the match filter — e.g. an
+   * anonymize keyed on `_id` leaves the row in place, so absence must be
+   * proven by querying the redacted identifier instead.
+   */
+  verifyFilter?: (scope: string) => Record<string, unknown>;
+  /** Overrides the generated check name. */
+  verifyName?: string;
+}
+/** Prefix for the blocker raised when the run carries no scope value. */
+declare const SCOPE_REQUIRED = "CLEANUP_SCOPE_REQUIRED";
+/** Prefix for the blocker raised when the repository cannot be reached. */
+declare const REPOSITORY_UNAVAILABLE = "CLEANUP_REPOSITORY_UNAVAILABLE";
+/**
+ * Build a `CleanupStep` from a repository + declaration.
+ *
+ * Invariants this owns, so no caller can get them wrong:
+ *   - **fail-closed scoping** — no scope value, or no repository, is a
+ *     BLOCKER, never a silent no-op and never an unscoped purge (which would
+ *     hit every tenant);
+ *   - **cancellation** — checked before work starts and threaded to the kit so
+ *     a cancel lands between committed chunks, never mid-write;
+ *   - **honest failure** — a failing purge returns `ok: false` so the composer
+ *     stops the recipe (retention §8), and a thrown error is reported, never
+ *     swallowed;
+ *   - **verification** — absence is re-queried after the run, because a
+ *     processed count alone is never proof (§9).
+ */
+declare function definePurgeStep(repository: PurgeStepRepository | undefined, spec: PurgeStepSpec): CleanupStep;
+//#endregion
+export { PurgeStepRepository, PurgeStepSpec, REPOSITORY_UNAVAILABLE, SCOPE_REQUIRED, definePurgeStep };

package/dist/cleanup/define-purge-step.mjs

@@ -0,0 +1,107 @@
+//#region src/cleanup/define-purge-step.ts
+/** Prefix for the blocker raised when the run carries no scope value. */
+const SCOPE_REQUIRED = "CLEANUP_SCOPE_REQUIRED";
+/** Prefix for the blocker raised when the repository cannot be reached. */
+const REPOSITORY_UNAVAILABLE = "CLEANUP_REPOSITORY_UNAVAILABLE";
+function scopeOf(ctx, parameter) {
+	const raw = ctx.parameters?.[parameter];
+	return typeof raw === "string" && raw.length > 0 ? raw : void 0;
+}
+/**
+* Build a `CleanupStep` from a repository + declaration.
+*
+* Invariants this owns, so no caller can get them wrong:
+*   - **fail-closed scoping** — no scope value, or no repository, is a
+*     BLOCKER, never a silent no-op and never an unscoped purge (which would
+*     hit every tenant);
+*   - **cancellation** — checked before work starts and threaded to the kit so
+*     a cancel lands between committed chunks, never mid-write;
+*   - **honest failure** — a failing purge returns `ok: false` so the composer
+*     stops the recipe (retention §8), and a thrown error is reported, never
+*     swallowed;
+*   - **verification** — absence is re-queried after the run, because a
+*     processed count alone is never proof (§9).
+*/
+function definePurgeStep(repository, spec) {
+	const destructive = spec.strategy.type !== "skip";
+	const verifyName = spec.verifyName ?? `${spec.id}.verified`;
+	const filterFor = (scope) => spec.verifyFilter?.(scope) ?? { [spec.field]: scope };
+	return {
+		id: spec.id,
+		resource: spec.resource,
+		destructive,
+		async estimate(ctx) {
+			const scope = scopeOf(ctx, spec.parameter);
+			if (!scope) return {
+				resource: spec.resource,
+				estimated: 0,
+				blockers: [`${SCOPE_REQUIRED}:${spec.parameter}`]
+			};
+			if (!repository?.purgeByField) return {
+				resource: spec.resource,
+				estimated: 0,
+				blockers: [`${REPOSITORY_UNAVAILABLE}:${spec.id}`]
+			};
+			const estimated = await repository.countDocuments?.({ [spec.field]: scope }) ?? 0;
+			const blockers = await spec.guard?.(scope, ctx) ?? [];
+			return {
+				resource: spec.resource,
+				estimated,
+				...spec.retained === void 0 ? {} : { retained: spec.retained },
+				...blockers.length > 0 ? { blockers: [...blockers] } : {},
+				...spec.warnings === void 0 ? {} : { warnings: [...spec.warnings] }
+			};
+		},
+		async execute(ctx) {
+			await ctx.throwIfCancelled?.();
+			const scope = scopeOf(ctx, spec.parameter);
+			if (!scope || !repository?.purgeByField) return {
+				resource: spec.resource,
+				processed: 0,
+				ok: false,
+				error: scope ? `repository for '${spec.id}' is unavailable` : `missing run parameter '${spec.parameter}'`
+			};
+			try {
+				const result = await repository.purgeByField(spec.field, scope, spec.strategy, {
+					...spec.batchSize === void 0 ? {} : { batchSize: spec.batchSize },
+					...ctx.signal ? { signal: ctx.signal } : {},
+					onProgress: async (event) => {
+						await ctx.onProgress?.({
+							resource: spec.resource,
+							processed: event.processed
+						});
+					}
+				});
+				return {
+					resource: spec.resource,
+					processed: result.processed,
+					ok: result.ok,
+					...result.ok ? {} : { error: result.error?.message ?? "purge reported failure" }
+				};
+			} catch (error) {
+				return {
+					resource: spec.resource,
+					processed: 0,
+					ok: false,
+					error: error instanceof Error ? error.message : String(error)
+				};
+			}
+		},
+		async verify(ctx) {
+			const scope = scopeOf(ctx, spec.parameter);
+			if (!scope || !repository?.countDocuments) return [{
+				name: verifyName,
+				ok: false,
+				detail: "could not verify — no scope or no count support"
+			}];
+			const remaining = await repository.countDocuments(filterFor(scope));
+			return [{
+				name: verifyName,
+				ok: remaining === 0,
+				detail: remaining === 0 ? `no ${spec.resource} still match the scope` : `${remaining} row(s) still match — cleanup incomplete`
+			}];
+		}
+	};
+}
+//#endregion
+export { REPOSITORY_UNAVAILABLE, SCOPE_REQUIRED, definePurgeStep };

package/dist/cleanup/index.d.mts

@@ -1,2 +1,3 @@
 import { CleanupStep, CleanupStepCheck, CleanupStepContext, CleanupStepEstimate, CleanupStepExecuteContext, CleanupStepLogger, CleanupStepOutcome, CleanupStepProgress } from "./types.mjs";
-export type { CleanupStep, CleanupStepCheck, CleanupStepContext, CleanupStepEstimate, CleanupStepExecuteContext, CleanupStepLogger, CleanupStepOutcome, CleanupStepProgress };
+import { PurgeStepRepository, PurgeStepSpec, REPOSITORY_UNAVAILABLE, SCOPE_REQUIRED, definePurgeStep } from "./define-purge-step.mjs";
+export { type CleanupStep, type CleanupStepCheck, type CleanupStepContext, type CleanupStepEstimate, type CleanupStepExecuteContext, type CleanupStepLogger, type CleanupStepOutcome, type CleanupStepProgress, type PurgeStepRepository, type PurgeStepSpec, REPOSITORY_UNAVAILABLE, SCOPE_REQUIRED, definePurgeStep };

package/dist/cleanup/index.mjs

@@ -0,0 +1,2 @@
+import { REPOSITORY_UNAVAILABLE, SCOPE_REQUIRED, definePurgeStep } from "./define-purge-step.mjs";
+export { REPOSITORY_UNAVAILABLE, SCOPE_REQUIRED, definePurgeStep };

package/dist/filter/coerce-dates.d.mts

@@ -0,0 +1,65 @@
+//#region src/filter/coerce-dates.d.ts
+/**
+ * ISO-date coercion for record-shape filters — the canonical helper every
+ * kit shares.
+ *
+ * WHY THIS EXISTS. A URL carries strings (`?createdAt[gte]=2026-04-01`), but
+ * the stored column is a real date. On a `find`-family call Mongoose casts
+ * the query against the schema, so a string silently becomes a `Date` and
+ * everything works. **An aggregation `$match` stage gets no such casting** —
+ * and BSON type ordering makes `Date` (type 9) and `String` (type 2)
+ * non-comparable, so `{ createdAt: { $gte: '2026-04-01' } }` matches
+ * NOTHING against a Date field. Silent empty result, no error. The same
+ * hazard exists for any kit comparing a typed column to a string literal.
+ *
+ * Coercion therefore has to happen in the shared layer, before a kit emits
+ * its native predicate — which is what this module is for. It is
+ * DIALECT-PRESERVING (record in, record out): it never converts to the
+ * Filter IR, so a caller that hands over Mongo-dialect syntax gets
+ * Mongo-dialect syntax back, just with dates typed correctly. That keeps it
+ * usable from `compileFilterToMongo`'s already-built-query passthrough
+ * branch, where converting to IR would lose operators the IR doesn't model.
+ *
+ * Two shapes are handled, because both reach the compile boundary:
+ *   - **bare shorthand** — `{ gte: '…' }`, what Fastify parses out of arc's
+ *     bracket-syntax URL params, and
+ *   - **`$`-prefixed** — `{ $gte: '…' }`, already-built Mongo/policy syntax.
+ *
+ * Logical wrappers (`$and` / `$or` / `$nor` / `$not`) are recursed — the
+ * same operator set {@link policyRecordToFilter} walks, kept deliberately in
+ * sync. Without recursion a date range nested under `$and` (exactly what a
+ * tenant/policy-scope merge produces when it conjoins a policy filter with a
+ * caller filter) is never coerced.
+ */
+/**
+ * Tight ISO-8601 pattern — date-only through millisecond precision with an
+ * optional timezone. Anchored at BOTH ends on purpose: a loose prefix-only
+ * match (`/^\d{4}-\d{2}-\d{2}/`) also swallows strings that merely START
+ * with something date-shaped (order numbers, slugs, serials), silently
+ * rewriting a legitimate string predicate into a Date one.
+ *
+ * THE single source of truth — `query-parser/coerce.ts` imports it rather
+ * than keeping a second copy.
+ */
+declare const ISO_DATE_PATTERN: RegExp;
+/**
+ * Coerce one value to a `Date` when it is an unambiguous ISO-8601 string.
+ * Anything else — including an unparseable date-shaped string — is returned
+ * untouched, so this is always safe to apply.
+ */
+declare function tryCoerceIsoDate(value: unknown): unknown;
+/**
+ * Walk a record-shape filter and coerce ISO-date strings on range operators
+ * to `Date`, recursing through logical wrappers. Returns a new object;
+ * the input is never mutated. Non-range operators, real nested documents,
+ * and already-typed values pass through unchanged.
+ *
+ * @example
+ * ```ts
+ * coerceFilterDates({ $and: [{ createdAt: { $gte: '2026-04-01' } }] })
+ * // → { $and: [{ createdAt: { $gte: Date(2026-04-01) } }] }
+ * ```
+ */
+declare function coerceFilterDates(filter: Record<string, unknown>): Record<string, unknown>;
+//#endregion
+export { ISO_DATE_PATTERN, coerceFilterDates, tryCoerceIsoDate };

package/dist/filter/coerce-dates.mjs

@@ -0,0 +1,125 @@
+//#region src/filter/coerce-dates.ts
+/**
+* ISO-date coercion for record-shape filters — the canonical helper every
+* kit shares.
+*
+* WHY THIS EXISTS. A URL carries strings (`?createdAt[gte]=2026-04-01`), but
+* the stored column is a real date. On a `find`-family call Mongoose casts
+* the query against the schema, so a string silently becomes a `Date` and
+* everything works. **An aggregation `$match` stage gets no such casting** —
+* and BSON type ordering makes `Date` (type 9) and `String` (type 2)
+* non-comparable, so `{ createdAt: { $gte: '2026-04-01' } }` matches
+* NOTHING against a Date field. Silent empty result, no error. The same
+* hazard exists for any kit comparing a typed column to a string literal.
+*
+* Coercion therefore has to happen in the shared layer, before a kit emits
+* its native predicate — which is what this module is for. It is
+* DIALECT-PRESERVING (record in, record out): it never converts to the
+* Filter IR, so a caller that hands over Mongo-dialect syntax gets
+* Mongo-dialect syntax back, just with dates typed correctly. That keeps it
+* usable from `compileFilterToMongo`'s already-built-query passthrough
+* branch, where converting to IR would lose operators the IR doesn't model.
+*
+* Two shapes are handled, because both reach the compile boundary:
+*   - **bare shorthand** — `{ gte: '…' }`, what Fastify parses out of arc's
+*     bracket-syntax URL params, and
+*   - **`$`-prefixed** — `{ $gte: '…' }`, already-built Mongo/policy syntax.
+*
+* Logical wrappers (`$and` / `$or` / `$nor` / `$not`) are recursed — the
+* same operator set {@link policyRecordToFilter} walks, kept deliberately in
+* sync. Without recursion a date range nested under `$and` (exactly what a
+* tenant/policy-scope merge produces when it conjoins a policy filter with a
+* caller filter) is never coerced.
+*/
+/**
+* Tight ISO-8601 pattern — date-only through millisecond precision with an
+* optional timezone. Anchored at BOTH ends on purpose: a loose prefix-only
+* match (`/^\d{4}-\d{2}-\d{2}/`) also swallows strings that merely START
+* with something date-shaped (order numbers, slugs, serials), silently
+* rewriting a legitimate string predicate into a Date one.
+*
+* THE single source of truth — `query-parser/coerce.ts` imports it rather
+* than keeping a second copy.
+*/
+const ISO_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,3})?)?(?:Z|[+-]\d{2}:?\d{2})?)?$/;
+/**
+* Coerce one value to a `Date` when it is an unambiguous ISO-8601 string.
+* Anything else — including an unparseable date-shaped string — is returned
+* untouched, so this is always safe to apply.
+*/
+function tryCoerceIsoDate(value) {
+	if (typeof value !== "string" || !ISO_DATE_PATTERN.test(value)) return value;
+	const parsed = new Date(value);
+	return Number.isNaN(parsed.getTime()) ? value : parsed;
+}
+/**
+* Range operators whose operand is compared by BSON/SQL type and therefore
+* must be a real date, not a string. Equality is deliberately EXCLUDED:
+* `{ status: '2026-01-01' }` is far more likely a string id than a date, and
+* an `eq` against a Date column is the one case a caller can express exactly
+* by passing a `Date`. Both bare and `$`-prefixed spellings are listed.
+*/
+const RANGE_OPS = /* @__PURE__ */ new Set([
+	"gt",
+	"gte",
+	"lt",
+	"lte",
+	"$gt",
+	"$gte",
+	"$lt",
+	"$lte"
+]);
+/** Logical operators whose operand is an ARRAY of sub-filters. */
+const LOGICAL_ARRAY_OPS = /* @__PURE__ */ new Set([
+	"$and",
+	"$or",
+	"$nor",
+	"and",
+	"or",
+	"nor"
+]);
+/** Logical operators whose operand is a SINGLE nested sub-filter. */
+const LOGICAL_OBJECT_OPS = /* @__PURE__ */ new Set(["$not", "not"]);
+function isPlainObject(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value) && !(value instanceof Date);
+}
+/**
+* Walk a record-shape filter and coerce ISO-date strings on range operators
+* to `Date`, recursing through logical wrappers. Returns a new object;
+* the input is never mutated. Non-range operators, real nested documents,
+* and already-typed values pass through unchanged.
+*
+* @example
+* ```ts
+* coerceFilterDates({ $and: [{ createdAt: { $gte: '2026-04-01' } }] })
+* // → { $and: [{ createdAt: { $gte: Date(2026-04-01) } }] }
+* ```
+*/
+function coerceFilterDates(filter) {
+	const out = {};
+	for (const [key, value] of Object.entries(filter)) {
+		if (LOGICAL_ARRAY_OPS.has(key) && Array.isArray(value)) {
+			out[key] = value.map((entry) => isPlainObject(entry) ? coerceFilterDates(entry) : entry);
+			continue;
+		}
+		if (LOGICAL_OBJECT_OPS.has(key) && isPlainObject(value)) {
+			out[key] = coerceFilterDates(value);
+			continue;
+		}
+		if (isPlainObject(value)) {
+			let changed = false;
+			const coerced = {};
+			for (const [op, operand] of Object.entries(value)) if (RANGE_OPS.has(op)) {
+				const next = tryCoerceIsoDate(operand);
+				coerced[op] = next;
+				if (next !== operand) changed = true;
+			} else coerced[op] = operand;
+			out[key] = changed ? coerced : value;
+			continue;
+		}
+		out[key] = value;
+	}
+	return out;
+}
+//#endregion
+export { ISO_DATE_PATTERN, coerceFilterDates, tryCoerceIsoDate };

package/dist/filter/index.d.mts

@@ -1,9 +1,10 @@
 import { Filter, FilterAnd, FilterEq, FilterExists, FilterFalse, FilterGt, FilterGte, FilterIn, FilterLike, FilterLt, FilterLte, FilterNe, FilterNin, FilterNot, FilterOp, FilterOr, FilterRaw, FilterRegex, FilterTrue } from "./types.mjs";
 import { FALSE, TRUE, and, anyOf as in_, between, contains, endsWith, eq, exists, gt, gte, iEq, invert as not, isNotNull, isNull, like, lt, lte, ne, nin, or, raw, regex, startsWith } from "./builders.mjs";
+import { ISO_DATE_PATTERN, coerceFilterDates, tryCoerceIsoDate } from "./coerce-dates.mjs";
 import { recordToFilter } from "./from-record.mjs";
 import { isFilter } from "./guard.mjs";
 import { asPredicate, matchFilter } from "./match.mjs";
 import { matchesRecordFilter, policyRecordToFilter } from "./match-record.mjs";
 import { SCOPE_ANY, buildTenantScope, mergeScope } from "./scope.mjs";
 import { collectFields, mapFilter, walkFilter } from "./walk.mjs";
-export { FALSE, type Filter, type FilterAnd, type FilterEq, type FilterExists, type FilterFalse, type FilterGt, type FilterGte, type FilterIn, type FilterLike, type FilterLt, type FilterLte, type FilterNe, type FilterNin, type FilterNot, type FilterOp, type FilterOr, type FilterRaw, type FilterRegex, type FilterTrue, SCOPE_ANY, TRUE, and, in_ as anyOf, asPredicate, between, buildTenantScope, collectFields, contains, endsWith, eq, exists, gt, gte, iEq, in_, not as invert, isFilter, isNotNull, isNull, like, lt, lte, mapFilter, matchFilter, matchesRecordFilter, mergeScope, ne, nin, nin as noneOf, not, or, policyRecordToFilter, raw, recordToFilter, regex, startsWith, walkFilter };
+export { FALSE, type Filter, type FilterAnd, type FilterEq, type FilterExists, type FilterFalse, type FilterGt, type FilterGte, type FilterIn, type FilterLike, type FilterLt, type FilterLte, type FilterNe, type FilterNin, type FilterNot, type FilterOp, type FilterOr, type FilterRaw, type FilterRegex, type FilterTrue, ISO_DATE_PATTERN, SCOPE_ANY, TRUE, and, in_ as anyOf, asPredicate, between, buildTenantScope, coerceFilterDates, collectFields, contains, endsWith, eq, exists, gt, gte, iEq, in_, not as invert, isFilter, isNotNull, isNull, like, lt, lte, mapFilter, matchFilter, matchesRecordFilter, mergeScope, ne, nin, nin as noneOf, not, or, policyRecordToFilter, raw, recordToFilter, regex, startsWith, tryCoerceIsoDate, walkFilter };

package/dist/filter/index.mjs

@@ -1,8 +1,9 @@
 import { isFilter } from "./guard.mjs";
 import { collectFields, mapFilter, walkFilter } from "./walk.mjs";
 import { FALSE, TRUE, and, anyOf as in_, between, contains, endsWith, eq, exists, gt, gte, iEq, invert as not, isNotNull, isNull, like, lt, lte, ne, nin, or, raw, regex, startsWith } from "./builders.mjs";
+import { ISO_DATE_PATTERN, coerceFilterDates, tryCoerceIsoDate } from "./coerce-dates.mjs";
 import { recordToFilter } from "./from-record.mjs";
 import { asPredicate, matchFilter } from "./match.mjs";
 import { matchesRecordFilter, policyRecordToFilter } from "./match-record.mjs";
 import { SCOPE_ANY, buildTenantScope, mergeScope } from "./scope.mjs";
-export { FALSE, SCOPE_ANY, TRUE, and, in_ as anyOf, asPredicate, between, buildTenantScope, collectFields, contains, endsWith, eq, exists, gt, gte, iEq, in_, not as invert, isFilter, isNotNull, isNull, like, lt, lte, mapFilter, matchFilter, matchesRecordFilter, mergeScope, ne, nin, nin as noneOf, not, or, policyRecordToFilter, raw, recordToFilter, regex, startsWith, walkFilter };
+export { FALSE, ISO_DATE_PATTERN, SCOPE_ANY, TRUE, and, in_ as anyOf, asPredicate, between, buildTenantScope, coerceFilterDates, collectFields, contains, endsWith, eq, exists, gt, gte, iEq, in_, not as invert, isFilter, isNotNull, isNull, like, lt, lte, mapFilter, matchFilter, matchesRecordFilter, mergeScope, ne, nin, nin as noneOf, not, or, policyRecordToFilter, raw, recordToFilter, regex, startsWith, tryCoerceIsoDate, walkFilter };

package/dist/query-parser/coerce.mjs

@@ -1,4 +1,11 @@
+import { ISO_DATE_PATTERN } from "../filter/coerce-dates.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).
+*/
 const BOOLEAN_STRINGS = /* @__PURE__ */ new Set([
 	"true",
 	"1",
@@ -11,7 +18,7 @@ const FALSEY_STRINGS = /* @__PURE__ */ new Set([
 	"no",
 	"off"
 ]);
-const ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,3})?)?(?:Z|[+-]\d{2}:?\d{2})?)?$/;
+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`,

package/dist/tenant/index.d.mts

@@ -1,3 +1,3 @@
 import { ResolvedTenantConfig, TenantConfig, TenantFieldType, TenantStrategy } from "./types.mjs";
-import { DEFAULT_TENANT_CONFIG, resolveTenantConfig } from "./resolve.mjs";
-export { DEFAULT_TENANT_CONFIG, type ResolvedTenantConfig, type TenantConfig, type TenantFieldType, type TenantStrategy, resolveTenantConfig };
+import { DEFAULT_TENANT_CONFIG, resolveTenantConfig, resolveTenantField } from "./resolve.mjs";
+export { DEFAULT_TENANT_CONFIG, type ResolvedTenantConfig, type TenantConfig, type TenantFieldType, type TenantStrategy, resolveTenantConfig, resolveTenantField };

package/dist/tenant/index.mjs

@@ -1,2 +1,2 @@
-import { DEFAULT_TENANT_CONFIG, resolveTenantConfig } from "./resolve.mjs";
-export { DEFAULT_TENANT_CONFIG, resolveTenantConfig };
+import { DEFAULT_TENANT_CONFIG, resolveTenantConfig, resolveTenantField } from "./resolve.mjs";
+export { DEFAULT_TENANT_CONFIG, resolveTenantConfig, resolveTenantField };

package/dist/tenant/resolve.d.mts

@@ -12,5 +12,21 @@ import { ResolvedTenantConfig, TenantConfig } from "./types.mjs";
 type TenantDefaults = { [K in 'strategy' | 'enabled' | 'tenantField' | 'fieldType' | 'ref' | 'contextKey' | 'required']-?: Exclude<TenantConfig[K], undefined>; };
 declare const DEFAULT_TENANT_CONFIG: TenantDefaults;
 declare function resolveTenantConfig(config?: TenantConfig | boolean): ResolvedTenantConfig;
+/**
+ * The single `tenantField` value a resource layer wants, or `false` when the
+ * option disables scoping entirely.
+ *
+ * Packages composing an arc resource need exactly this shape for
+ * `defineResource({ tenantField })`, and four spine modules independently
+ * hand-rolled it — each re-deriving `'organizationId'` as the default and
+ * unwrapping `{ tenantField }` by hand. One of those copies omitted the
+ * disable branch, so that package silently could not be configured
+ * company-wide. This wraps {@link resolveTenantConfig} so the default, the
+ * disable semantics, and the object-unwrapping have ONE definition.
+ *
+ * `false` / `{ enabled: false }` / `{ strategy: 'none' }` all mean "no tenant
+ * scoping" and all return `false` — callers get one thing to branch on.
+ */
+declare function resolveTenantField(config?: TenantConfig | boolean): string | false;
 //#endregion
-export { DEFAULT_TENANT_CONFIG, resolveTenantConfig };
+export { DEFAULT_TENANT_CONFIG, resolveTenantConfig, resolveTenantField };

package/dist/tenant/resolve.mjs

@@ -51,5 +51,25 @@ function resolveTenantConfig(config) {
 		enabled: cleaned.enabled ?? true
 	};
 }
+/**
+* The single `tenantField` value a resource layer wants, or `false` when the
+* option disables scoping entirely.
+*
+* Packages composing an arc resource need exactly this shape for
+* `defineResource({ tenantField })`, and four spine modules independently
+* hand-rolled it — each re-deriving `'organizationId'` as the default and
+* unwrapping `{ tenantField }` by hand. One of those copies omitted the
+* disable branch, so that package silently could not be configured
+* company-wide. This wraps {@link resolveTenantConfig} so the default, the
+* disable semantics, and the object-unwrapping have ONE definition.
+*
+* `false` / `{ enabled: false }` / `{ strategy: 'none' }` all mean "no tenant
+* scoping" and all return `false` — callers get one thing to branch on.
+*/
+function resolveTenantField(config) {
+	const resolved = resolveTenantConfig(config);
+	if (!resolved.enabled || resolved.strategy === "none") return false;
+	return resolved.tenantField;
+}
 //#endregion
-export { DEFAULT_TENANT_CONFIG, resolveTenantConfig };
+export { DEFAULT_TENANT_CONFIG, resolveTenantConfig, resolveTenantField };

package/dist/testing/index.d.mts

@@ -2,6 +2,6 @@ import { AggregateOpsSupport } from "../repository/capabilities.mjs";
 import { ConformanceContext, ConformanceDoc, ConformanceFeatures, ConformanceHarness } from "./types.mjs";
 import { runStandardRepoConformance } from "./conformance.mjs";
 import { LockConformanceHarness, runLockAdapterConformance } from "./lock-conformance.mjs";
-import { UsageConformanceHarness, runUsageStoreContract } from "./usage-conformance.mjs";
 import { PurgeConformanceContext, PurgeConformanceHarness, runPurgeConformance } from "./purge-conformance.mjs";
+import { UsageConformanceHarness, runUsageStoreContract } from "./usage-conformance.mjs";
 export { type AggregateOpsSupport, type ConformanceContext, type ConformanceDoc, type ConformanceFeatures, type ConformanceHarness, type LockConformanceHarness, type PurgeConformanceContext, type PurgeConformanceHarness, type UsageConformanceHarness, runLockAdapterConformance, runPurgeConformance, runStandardRepoConformance, runUsageStoreContract };

package/dist/testing/index.mjs

@@ -1,5 +1,5 @@
 import { runStandardRepoConformance } from "./conformance.mjs";
 import { runLockAdapterConformance } from "./lock-conformance.mjs";
-import { runUsageStoreContract } from "./usage-conformance.mjs";
 import { runPurgeConformance } from "./purge-conformance.mjs";
+import { runUsageStoreContract } from "./usage-conformance.mjs";
 export { runLockAdapterConformance, runPurgeConformance, runStandardRepoConformance, runUsageStoreContract };

package/package.json

@@ -1,180 +1,180 @@
 {
-  "name": "@classytic/repo-core",
-  "version": "0.17.0",
-  "description": "Driver-agnostic repository primitives: hooks, Filter IR, operations, pagination, cache contract. Foundation for mongokit, sqlitekit, pgkit, and prismakit. Lean by design — no plugins ship here; each kit owns its own.",
-  "type": "module",
-  "sideEffects": false,
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE",
-    "CHANGELOG.md"
-  ],
-  "engines": {
-    "node": ">=22"
-  },
-  "exports": {
-    "./hooks": {
-      "types": "./dist/hooks/index.d.mts",
-      "default": "./dist/hooks/index.mjs"
-    },
-    "./operations": {
-      "types": "./dist/operations/index.d.mts",
-      "default": "./dist/operations/index.mjs"
-    },
-    "./errors": {
-      "types": "./dist/errors/index.d.mts",
-      "default": "./dist/errors/index.mjs"
-    },
-    "./pagination": {
-      "types": "./dist/pagination/index.d.mts",
-      "default": "./dist/pagination/index.mjs"
-    },
-    "./repository": {
-      "types": "./dist/repository/index.d.mts",
-      "default": "./dist/repository/index.mjs"
-    },
-    "./filter": {
-      "types": "./dist/filter/index.d.mts",
-      "default": "./dist/filter/index.mjs"
-    },
-    "./update": {
-      "types": "./dist/update/index.d.mts",
-      "default": "./dist/update/index.mjs"
-    },
-    "./query-parser": {
-      "types": "./dist/query-parser/index.d.mts",
-      "default": "./dist/query-parser/index.mjs"
-    },
-    "./context": {
-      "types": "./dist/context/index.d.mts",
-      "default": "./dist/context/index.mjs"
-    },
-    "./cache": {
-      "types": "./dist/cache/index.d.mts",
-      "default": "./dist/cache/index.mjs"
-    },
-    "./events": {
-      "types": "./dist/events/index.d.mts",
-      "default": "./dist/events/index.mjs"
-    },
-    "./schema": {
-      "types": "./dist/schema/index.d.mts",
-      "default": "./dist/schema/index.mjs"
-    },
-    "./testing": {
-      "types": "./dist/testing/index.d.mts",
-      "default": "./dist/testing/index.mjs"
-    },
-    "./tenant": {
-      "types": "./dist/tenant/index.d.mts",
-      "default": "./dist/tenant/index.mjs"
-    },
-    "./lookup": {
-      "types": "./dist/lookup/index.d.mts",
-      "default": "./dist/lookup/index.mjs"
-    },
-    "./adapter": {
-      "types": "./dist/adapter/index.d.mts",
-      "default": "./dist/adapter/index.mjs"
-    },
-    "./better-auth": {
-      "types": "./dist/better-auth/index.d.mts",
-      "default": "./dist/better-auth/index.mjs"
-    },
-    "./aggregate": {
-      "types": "./dist/aggregate/index.d.mts",
-      "default": "./dist/aggregate/index.mjs"
-    },
-    "./plugins": {
-      "types": "./dist/plugins/index.d.mts",
-      "default": "./dist/plugins/index.mjs"
-    },
-    "./lock": {
-      "types": "./dist/lock/index.d.mts",
-      "default": "./dist/lock/index.mjs"
-    },
-    "./usage": {
-      "types": "./dist/usage/index.d.mts",
-      "default": "./dist/usage/index.mjs"
-    },
-    "./package.json": "./package.json",
-    "./sync": {
-      "types": "./dist/sync/index.d.mts",
-      "default": "./dist/sync/index.mjs"
-    },
-    "./cleanup": {
-      "types": "./dist/cleanup/index.d.mts",
-      "default": "./dist/cleanup/index.mjs"
-    }
-  },
-  "keywords": [
-    "repository",
-    "repository-pattern",
-    "data-access",
-    "hooks",
-    "filter-ir",
-    "pagination",
-    "cursor-pagination",
-    "keyset-pagination",
-    "plugin-based",
-    "driver-agnostic",
-    "typescript",
-    "esm"
-  ],
-  "author": "Classytic <classytic.dev@gmail.com> (https://github.com/classytic)",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/classytic/repo-core.git"
-  },
-  "bugs": {
-    "url": "https://github.com/classytic/repo-core/issues"
-  },
-  "homepage": "https://github.com/classytic/repo-core#readme",
-  "scripts": {
-    "build": "tsdown",
-    "dev": "tsdown --watch",
-    "test": "vitest run --project unit --project integration",
-    "test:unit": "vitest run --project unit",
-    "test:integration": "vitest run --project integration",
-    "test:e2e": "vitest run --project e2e",
-    "test:all": "vitest run",
-    "test:watch": "vitest --project unit --project integration",
-    "bench": "vitest bench --run --project bench",
-    "test:coverage": "vitest run --coverage",
-    "typecheck": "tsc --noEmit && tsc -p tsconfig.test.json",
-    "lint": "biome check src tests",
-    "lint:fix": "biome check src tests --write",
-    "format": "biome format src tests --write",
-    "check": "biome ci src tests --diagnostic-level=error",
-    "knip": "knip",
-    "push": "classytic-push",
-    "prepublishOnly": "npm run check && npm run build && npm run typecheck && npm test",
-    "release:tag": "node -e \"require('child_process').execSync('npm run push -- v'+require('./package.json').version,{stdio:'inherit'})\"",
-    "release": "npm run push -- main && npm run release:tag && npm publish",
-    "publish:dry": "npm publish --dry-run --access public",
-    "publish:npm": "npm publish --access public"
-  },
-  "devDependencies": {
-    "@arethetypeswrong/cli": "^0.18.2",
-    "@biomejs/biome": "^2.4.12",
-    "@classytic/dev-tools": "^0.2.0",
-    "@types/node": "^22.0.0",
-    "@vitest/coverage-v8": "^4.1.4",
-    "fast-check": "^4.7.0",
-    "knip": "^6.3.0",
-    "publint": "^0.3.18",
-    "tsdown": "^0.22.5",
-    "typescript": "^7.0.2",
-    "vitest": "^4.1.4"
-  },
-  "peerDependencies": {
-    "vitest": "^3.0.0 || ^4.0.0"
-  },
-  "peerDependenciesMeta": {
-    "vitest": {
-      "optional": true
-    }
-  }
+	"name": "@classytic/repo-core",
+	"version": "0.19.0",
+	"description": "Driver-agnostic repository primitives: hooks, Filter IR, operations, pagination, cache contract. Foundation for mongokit, sqlitekit, pgkit, and prismakit. Lean by design — no plugins ship here; each kit owns its own.",
+	"type": "module",
+	"sideEffects": false,
+	"files": [
+		"dist",
+		"README.md",
+		"LICENSE",
+		"CHANGELOG.md"
+	],
+	"engines": {
+		"node": ">=22"
+	},
+	"exports": {
+		"./hooks": {
+			"types": "./dist/hooks/index.d.mts",
+			"default": "./dist/hooks/index.mjs"
+		},
+		"./operations": {
+			"types": "./dist/operations/index.d.mts",
+			"default": "./dist/operations/index.mjs"
+		},
+		"./errors": {
+			"types": "./dist/errors/index.d.mts",
+			"default": "./dist/errors/index.mjs"
+		},
+		"./pagination": {
+			"types": "./dist/pagination/index.d.mts",
+			"default": "./dist/pagination/index.mjs"
+		},
+		"./repository": {
+			"types": "./dist/repository/index.d.mts",
+			"default": "./dist/repository/index.mjs"
+		},
+		"./filter": {
+			"types": "./dist/filter/index.d.mts",
+			"default": "./dist/filter/index.mjs"
+		},
+		"./update": {
+			"types": "./dist/update/index.d.mts",
+			"default": "./dist/update/index.mjs"
+		},
+		"./query-parser": {
+			"types": "./dist/query-parser/index.d.mts",
+			"default": "./dist/query-parser/index.mjs"
+		},
+		"./context": {
+			"types": "./dist/context/index.d.mts",
+			"default": "./dist/context/index.mjs"
+		},
+		"./cache": {
+			"types": "./dist/cache/index.d.mts",
+			"default": "./dist/cache/index.mjs"
+		},
+		"./events": {
+			"types": "./dist/events/index.d.mts",
+			"default": "./dist/events/index.mjs"
+		},
+		"./schema": {
+			"types": "./dist/schema/index.d.mts",
+			"default": "./dist/schema/index.mjs"
+		},
+		"./testing": {
+			"types": "./dist/testing/index.d.mts",
+			"default": "./dist/testing/index.mjs"
+		},
+		"./tenant": {
+			"types": "./dist/tenant/index.d.mts",
+			"default": "./dist/tenant/index.mjs"
+		},
+		"./lookup": {
+			"types": "./dist/lookup/index.d.mts",
+			"default": "./dist/lookup/index.mjs"
+		},
+		"./adapter": {
+			"types": "./dist/adapter/index.d.mts",
+			"default": "./dist/adapter/index.mjs"
+		},
+		"./better-auth": {
+			"types": "./dist/better-auth/index.d.mts",
+			"default": "./dist/better-auth/index.mjs"
+		},
+		"./aggregate": {
+			"types": "./dist/aggregate/index.d.mts",
+			"default": "./dist/aggregate/index.mjs"
+		},
+		"./plugins": {
+			"types": "./dist/plugins/index.d.mts",
+			"default": "./dist/plugins/index.mjs"
+		},
+		"./lock": {
+			"types": "./dist/lock/index.d.mts",
+			"default": "./dist/lock/index.mjs"
+		},
+		"./usage": {
+			"types": "./dist/usage/index.d.mts",
+			"default": "./dist/usage/index.mjs"
+		},
+		"./package.json": "./package.json",
+		"./sync": {
+			"types": "./dist/sync/index.d.mts",
+			"default": "./dist/sync/index.mjs"
+		},
+		"./cleanup": {
+			"types": "./dist/cleanup/index.d.mts",
+			"default": "./dist/cleanup/index.mjs"
+		}
+	},
+	"keywords": [
+		"repository",
+		"repository-pattern",
+		"data-access",
+		"hooks",
+		"filter-ir",
+		"pagination",
+		"cursor-pagination",
+		"keyset-pagination",
+		"plugin-based",
+		"driver-agnostic",
+		"typescript",
+		"esm"
+	],
+	"author": "Classytic <classytic.dev@gmail.com> (https://github.com/classytic)",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/classytic/repo-core.git"
+	},
+	"bugs": {
+		"url": "https://github.com/classytic/repo-core/issues"
+	},
+	"homepage": "https://github.com/classytic/repo-core#readme",
+	"scripts": {
+		"build": "tsdown",
+		"dev": "tsdown --watch",
+		"test": "vitest run --project unit --project integration",
+		"test:unit": "vitest run --project unit",
+		"test:integration": "vitest run --project integration",
+		"test:e2e": "vitest run --project e2e",
+		"test:all": "vitest run",
+		"test:watch": "vitest --project unit --project integration",
+		"bench": "vitest bench --run --project bench",
+		"test:coverage": "vitest run --coverage",
+		"typecheck": "tsc --noEmit && tsc -p tsconfig.test.json",
+		"lint": "biome check src tests",
+		"lint:fix": "biome check src tests --write",
+		"format": "biome format src tests --write",
+		"check": "biome ci src tests --diagnostic-level=error",
+		"knip": "knip",
+		"push": "classytic-push",
+		"prepublishOnly": "npm run check && npm run build && npm run typecheck && npm test",
+		"release:tag": "node -e \"require('child_process').execSync('npm run push -- v'+require('./package.json').version,{stdio:'inherit'})\"",
+		"release": "npm run push -- main && npm run release:tag && npm publish",
+		"publish:dry": "npm publish --dry-run --access public",
+		"publish:npm": "npm publish --access public"
+	},
+	"devDependencies": {
+		"@arethetypeswrong/cli": "^0.18.2",
+		"@biomejs/biome": "^2.4.12",
+		"@classytic/dev-tools": "^0.2.0",
+		"@types/node": "^22.0.0",
+		"@vitest/coverage-v8": "^4.1.4",
+		"fast-check": "^4.7.0",
+		"knip": "^6.3.0",
+		"publint": "^0.3.18",
+		"tsdown": "^0.22.5",
+		"typescript": "^7.0.2",
+		"vitest": "^4.1.4"
+	},
+	"peerDependencies": {
+		"vitest": "^3.0.0 || ^4.0.0"
+	},
+	"peerDependenciesMeta": {
+		"vitest": {
+			"optional": true
+		}
+	}
 }