@cullet/erp-core 1.4.0 → 2.0.0

package/src/core/errors/utils/json-safe.ts

@@ -30,18 +30,23 @@ function sanitizeValue(value: unknown, seen: WeakSet<object>): JsonSafeValue {
 
     const type = typeof value;
 
-    // Primitives
-    if (type === "string" || type === "number" || type === "boolean") {
+    // Primitives (non-finite numbers are not JSON-representable — placeholder)
+    if (type === "number") {
+        return Number.isFinite(value)
+            ? (value as number)
+            : NON_SERIALIZABLE_PLACEHOLDER;
+    }
+    if (type === "string" || type === "boolean") {
         return value as JsonSafeValue;
     }
 
+    // `undefined` only reaches here as an array item: object properties with
+    // undefined values are omitted by the plain-object branch below. Both
+    // mirror `JSON.stringify` semantics.
+    if (value === undefined) return null;
+
     // Non-serializable primitives
-    if (
-        type === "bigint" ||
-        type === "function" ||
-        type === "symbol" ||
-        value === undefined
-    ) {
+    if (type === "bigint" || type === "function" || type === "symbol") {
         return NON_SERIALIZABLE_PLACEHOLDER;
     }
 
@@ -69,7 +74,22 @@ function sanitizeValue(value: unknown, seen: WeakSet<object>): JsonSafeValue {
     seen.add(value);
     const result: Record<string, JsonSafeValue> = {};
     for (const [key, val] of Object.entries(value)) {
-        result[key] = sanitizeValue(val, seen);
+        if (val === undefined) continue;
+        const sanitized = sanitizeValue(val, seen);
+        if (key === "__proto__") {
+            // Plain `result.__proto__ = x` would reparent `result` instead of
+            // creating an own data property, silently dropping the key. Define
+            // it explicitly so `__proto__` survives as data — matching how
+            // JSON.stringify/JSON.parse round-trip it.
+            Object.defineProperty(result, key, {
+                value: sanitized,
+                enumerable: true,
+                writable: true,
+                configurable: true,
+            });
+        } else {
+            result[key] = sanitized;
+        }
     }
     seen.delete(value);
     return result;
@@ -82,11 +102,14 @@ function sanitizeValue(value: unknown, seen: WeakSet<object>): JsonSafeValue {
 /**
  * Ensures metadata is JSON-serializable.
  *
- * **Allowed:** string, number, boolean, null, arrays, and plain objects.
+ * **Allowed:** finite number, string, boolean, null, arrays, and plain objects.
+ *
+ * **Dropped (mirroring `JSON.stringify`):** object properties whose value is
+ * `undefined` (the key is omitted); an `undefined` array item becomes `null`.
  *
  * **Converted to placeholder:** Date, BigInt, class instances, functions,
- * symbols, undefined, and circular references (which would otherwise make
- * `JSON.stringify` throw).
+ * symbols, non-finite numbers (`NaN`/`Infinity`), and circular references
+ * (which would otherwise make `JSON.stringify` throw).
  *
  * @throws {TypeError} If `input` is not a plain object at the root level.
  */

package/src/core/errors/validation-error.ts

@@ -38,14 +38,17 @@ class ValidationError extends AppError {
             field: field.value,
             validationCode: code.value,
         };
+        // `field`/`validationCode` spread last so caller metadata is merged
+        // over them without ever overwriting them by accident.
         const mergedMetadata = options?.metadata
-            ? { ...baseMetadata, ...options.metadata }
+            ? { ...options.metadata, ...baseMetadata }
             : baseMetadata;
 
         super(message, ErrorCodes.validation, {
             ...options,
             metadata: mergedMetadata,
         });
+        Object.freeze(this);
     }
 }
 

package/src/core/exceptions/business-rule-violation-exception.ts

@@ -4,8 +4,9 @@ class BusinessRuleViolationException extends DomainException {
     constructor(
         public readonly rule: string,
         message: string,
+        options?: { cause?: unknown },
     ) {
-        super(message);
+        super(message, options);
     }
 }
 

package/src/core/exceptions/domain-exception.ts

@@ -1,6 +1,14 @@
 abstract class DomainException extends Error {
-    constructor(message: string) {
+    // ES2020's `Error` lib type does not declare `cause`; mirror the sibling
+    // `AppError` and carry it explicitly so a domain exception can wrap the
+    // lower-level failure that triggered it. Assigned rather than passed to
+    // `super` to stay independent of the ES2022 `Error(message, { cause })`
+    // overload the build target doesn't guarantee.
+    public readonly cause?: unknown;
+
+    constructor(message: string, options?: { cause?: unknown }) {
         super(message);
+        this.cause = options?.cause;
         Object.setPrototypeOf(this, new.target.prototype);
         this.name = new.target.name;
     }

package/src/core/exceptions/entity-not-found-exception.ts

@@ -4,8 +4,12 @@ class EntityNotFoundException extends DomainException {
     constructor(
         public readonly entityName: string,
         public readonly identifier: string,
+        options?: { cause?: unknown },
     ) {
-        super(`${entityName} with identifier ${identifier} was not found.`);
+        super(
+            `${entityName} with identifier ${identifier} was not found.`,
+            options,
+        );
     }
 }
 

package/src/core/exceptions/invalid-state-transition-exception.ts

@@ -6,9 +6,12 @@ class InvalidStateTransitionException<
     constructor(
         public readonly from: TState,
         public readonly to: TState,
-        message: string,
+        message?: string,
+        options?: { cause?: unknown },
     ) {
-        super(message);
+        // Compose a sensible default from `from`/`to` when no message is given,
+        // mirroring how EntityNotFoundException builds its own message.
+        super(message ?? `Cannot transition from ${from} to ${to}.`, options);
     }
 }
 

package/src/core/exceptions/invariant-violation-exception.ts

@@ -1,8 +1,8 @@
 import { DomainException } from "./domain-exception.js";
 
 class InvariantViolationException extends DomainException {
-    constructor(message: string) {
-        super(message);
+    constructor(message: string, options?: { cause?: unknown }) {
+        super(message, options);
     }
 }
 

package/src/core/exceptions/validation-code.ts

@@ -13,6 +13,20 @@ class ValidationCode {
         return new ValidationCode(value);
     }
 
+    public toString(): string {
+        return this.value;
+    }
+
+    public equals(other: ValidationCode): boolean {
+        return this.value === other.value;
+    }
+
+    // Serialize to the bare code string, so JSON.stringify of a violation
+    // yields "blank" rather than { "value": "blank" }. Mirrors ValidationField.
+    public toJSON(): string {
+        return this.value;
+    }
+
     // Common, domain-friendly codes
     public static readonly BLANK = new ValidationCode("blank");
     public static readonly REQUIRED = new ValidationCode("required");

package/src/core/exceptions/validation-exception.ts

@@ -1,4 +1,5 @@
 import { DomainException } from "./domain-exception.js";
+import { InvariantViolationException } from "./invariant-violation-exception.js";
 import { ValidationCode } from "./validation-code.js";
 import { ValidationField } from "./validation-field.js";
 
@@ -8,27 +9,65 @@ export interface ValidationViolation {
     readonly message: string;
 }
 
+// Extensible base for a single-field validation failure. Prefer throwing the
+// concrete InvalidValueException below so callers can `instanceof` the common
+// case; extend this directly only when you need a distinct validation subtype.
 class ValidationException extends DomainException {
     constructor(
         public readonly field: ValidationField,
         public readonly code: ValidationCode,
         message: string,
+        options?: { cause?: unknown },
     ) {
-        super(message);
+        super(message, options);
     }
 }
 
 // Carries multiple validation violations from a single operation (e.g. bulk validation).
 // Use when you need to report all field errors at once rather than failing on the first.
 class MultipleValidationException extends DomainException {
-    constructor(public readonly violations: readonly ValidationViolation[]) {
-        super(violations.map((v) => v.message).join("; "));
+    constructor(
+        public readonly violations: readonly ValidationViolation[],
+        options?: { cause?: unknown },
+    ) {
+        // An aggregate with no violations is a caller bug: it produces a
+        // messageless, contentless exception. Fail fast as a broken invariant.
+        if (violations.length === 0) {
+            throw new InvariantViolationException(
+                "MultipleValidationException requires at least one violation.",
+            );
+        }
+        super(violations.map((v) => v.message).join("; "), options);
+    }
+
+    // Number of accumulated violations (always >= 1).
+    get count(): number {
+        return this.violations.length;
+    }
+
+    // The first accumulated violation.
+    get first(): ValidationViolation {
+        return this.violations[0];
+    }
+
+    // Violations targeting the given field.
+    byField(field: ValidationField): readonly ValidationViolation[] {
+        return this.violations.filter((v) => v.field.equals(field));
     }
 }
 
+// The canonical concrete validation exception, thrown across the domain
+// (rbac/abac/policies/commands) when a single input value is invalid. Its
+// identity is exactly that: the named, catchable "a value was invalid" case,
+// versus ValidationException as the open base.
 class InvalidValueException extends ValidationException {
-    constructor(field: ValidationField, code: ValidationCode, message: string) {
-        super(field, code, message);
+    constructor(
+        field: ValidationField,
+        code: ValidationCode,
+        message: string,
+        options?: { cause?: unknown },
+    ) {
+        super(field, code, message, options);
     }
 }
 

package/src/core/exceptions/validation-field.ts

@@ -14,7 +14,11 @@ class ValidationField {
         return new ValidationField(value);
     }
 
-    // Creates a nested field path: parent.nested('child') -> 'parent.child'
+    // Creates a nested field path: parent.nested('child') -> 'parent.child'.
+    // The separator is a literal '.' and segments are NOT escaped, so
+    // of('a.b') and of('a').nested('b') collapse to the same path and compare
+    // equal — a field name that itself contains '.' is indistinguishable from
+    // a nested path. Keep segment names dot-free if that distinction matters.
     public nested(child: string | ValidationField): ValidationField {
         const childValue =
             child instanceof ValidationField ? child.value : child;
@@ -25,6 +29,12 @@ class ValidationField {
         return this.value;
     }
 
+    // Serialize to the bare field path, so JSON.stringify of a violation yields
+    // "email" rather than { "value": "email" }. Mirrors ValidationCode.
+    public toJSON(): string {
+        return this.value;
+    }
+
     public equals(other: ValidationField): boolean {
         return this.value === other.value;
     }

package/src/core/plugins/plugin.ts

@@ -9,11 +9,23 @@ import {
  * Registry that holds a set of plugins implementing a shared {@link PluginContract}
  * and resolves which of them answer a given extension point.
  *
- * Plugins are kept sorted by priority (descending). For a given method,
- * {@link invoke} either delegates to the highest-priority enabled plugin
- * (`'first'`) or folds every enabled plugin into a single value (`'pipeline'`).
- * When no plugin is enabled, the supplied `fallback` runs instead, so the host
- * always has defined behaviour even with an empty registry.
+ * Plugins are kept sorted by priority (descending); ties keep registration
+ * order (the sort is stable). For a given method, {@link invoke} either
+ * delegates to the highest-priority enabled plugin (`'first'`) or folds every
+ * enabled plugin into a single value (`'pipeline'`). When no plugin is enabled,
+ * the supplied `fallback` runs instead, so the host always has defined
+ * behaviour even with an empty registry.
+ *
+ * `name` is a unique key: registering a plugin whose name already exists
+ * replaces the previous one, so register/enable/disable/unregister all address
+ * the same single plugin.
+ *
+ * Plugins run arbitrary host code and are trusted: {@link invoke} does NOT wrap
+ * them in try/catch. A throwing plugin propagates to the caller (and, in
+ * `'pipeline'` mode, discards the accumulated result). Error handling, logging
+ * and retries are the host's responsibility by design — the registry's only
+ * defined-behaviour guarantee is `fallback` for an empty registry. Every plugin
+ * is expected to implement the full contract `P` (the types enforce it).
  *
  * @typeParam P - The plugin contract this manager coordinates.
  */
@@ -21,8 +33,10 @@ class PluginManager<P extends PluginContract> {
     /** Internal list, kept sorted by priority (desc). */
     private plugins: (P & BasePlugin)[] = [];
 
-    /** Registers one or more plugins and re-sorts by priority. */
+    /** Registers one or more plugins (replacing any with the same name) and re-sorts by priority. */
     public register(...plugins: (P & BasePlugin)[]): void {
+        const incoming = new Set(plugins.map((p) => p.name));
+        this.plugins = this.plugins.filter((p) => !incoming.has(p.name));
         this.plugins.push(...plugins);
         this.reorder();
     }
@@ -63,17 +77,14 @@ class PluginManager<P extends PluginContract> {
         opts: InvokeOptions<P, K>,
     ): ReturnType<P[K]> {
         const { mode = "first", fallback, reducer } = opts;
-        const enabled = this.list().filter((p) => method in p) as Array<
-            P & BasePlugin
-        >;
+        const enabled = this.list();
 
         if (enabled.length === 0) {
-            return (fallback as P[K])(...args);
+            return fallback(...args);
         }
 
         if (mode === "first") {
-            const fn = enabled[0][method] as P[K];
-            return fn(...args);
+            return enabled[0][method](...args);
         }
 
         const defaultReducer: PipelineReducer<ReturnType<P[K]>, P> = (
@@ -82,10 +93,9 @@ class PluginManager<P extends PluginContract> {
         ) => curr;
         const red = reducer ?? defaultReducer;
 
-        let acc: ReturnType<P[K]> = enabled[0][method]!(...args);
+        let acc: ReturnType<P[K]> = enabled[0][method](...args);
         enabled.slice(1).forEach((plugin, idx) => {
-            const res = plugin[method]!(...args);
-            acc = red(acc, res, plugin, idx + 1);
+            acc = red(acc, plugin[method](...args), plugin, idx + 1);
         });
         return acc;
     }

package/src/core/plugins/types.ts

@@ -6,7 +6,7 @@
 interface BasePlugin {
     /** Unique identifier, used for logs / debugging and for enable/disable. */
     readonly name: string;
-    /** Weight; the highest priority wins (default = 0). */
+    /** Weight; the highest priority wins (default = 0). Ties keep registration order. */
     readonly priority?: number;
     /** Shortcut to disable a plugin without removing it. */
     enabled?: boolean;
@@ -40,7 +40,9 @@ type PipelineReducer<R, P extends PluginContract> = (
 interface InvokeOptions<P extends PluginContract, K extends keyof P> {
     /**
      * `'first'`    → returns the first enabled plugin with the highest priority.
-     * `'pipeline'` → runs every enabled plugin, combining results via `reducer`.
+     * `'pipeline'` → fan-out + reduce: every enabled plugin runs against the
+     *   same original `args` (results are NOT chained into the next plugin's
+     *   input), and the results are folded together via `reducer`.
      * default = `'first'`.
      */
     mode?: "first" | "pipeline";

package/src/core/policies/asof/asof.ts

@@ -9,6 +9,18 @@ export interface DeriveAsOfOptions {
     readonly maxFutureYears?: number;
 }
 
+/**
+ * Derives the `asOf` instant an evaluation is pinned to.
+ *
+ * With `asOfSource: "CALLER_PROVIDED"` the instant comes from the reserved
+ * `seed.fields.asOf` key (a `Date`); with `"NOW"` it is the evaluation clock.
+ *
+ * The bound is intentionally asymmetric: a caller-provided `asOf` may be at
+ * most `maxFutureYears` in the future (a fat-finger / clock-skew guard against
+ * selecting a not-yet-in-force policy), but is unbounded in the past — querying
+ * how a policy stood at any historical instant is a first-class use of a
+ * temporal engine, so back-dating is never capped.
+ */
 export class PolicyAsOfResolver {
     private static resolveMaxFutureYears(
         options: DeriveAsOfOptions,

package/src/core/policies/catalog/policy-catalog-entry.ts

@@ -195,7 +195,9 @@ export class PolicyCatalogEntry {
     }
 
     equals(other: PolicyCatalogEntry): boolean {
-        return this.key.equals(other.key);
+        // Full variant identity (key + kind + engine/schema versions), not just
+        // the key: two variants under the same key are distinct entries.
+        return this.toVariantKey() === other.toVariantKey();
     }
 
     toJSON(): PolicyCatalogEntryProps {

package/src/core/policies/catalog/policy-catalog.ts

@@ -124,7 +124,11 @@ export class PolicyCatalog {
             return Result.ok(exactMatch);
         }
 
-        if (family.length === 1 && !family[0].hasExplicitVersionSelector()) {
+        if (
+            family.length === 1 &&
+            family[0].kind === params.kind &&
+            !family[0].hasExplicitVersionSelector()
+        ) {
             return Result.ok(family[0]);
         }
 

package/src/core/policies/context/context-builder.ts

@@ -32,6 +32,13 @@ interface ContextResolverCircuitState {
     readonly openUntilMs: number | null;
 }
 
+// The circuit breaker is keyed by context path alone, so its state is shared
+// across every seed a builder serves. This is intentional — the breaker guards
+// the backend behind a path, not a single tenant's request — but it means
+// failures resolving a path for one tenant can trip the breaker for others.
+// Give each isolated blast radius its own PolicyContextBuilder if that scope is
+// wrong for your host.
+
 export interface PolicyContextBuilderOptions {
     readonly defaultResolverResilience?: ContextResolverResilienceOptions;
     readonly now?: () => number;
@@ -296,6 +303,12 @@ export class PolicyContextBuilder {
             return execute();
         }
 
+        // The timeout is a race, not a cancellation: on timeout the losing
+        // resolver keeps running to completion in the background (there is no
+        // AbortSignal in the resolver contract). Combined with retry, a slow
+        // resolver can therefore be in flight more than once at a time — safe
+        // for the idempotent reads resolvers are required to be (see
+        // ContextValueResolver), a hazard for any resolver with side effects.
         let timeoutId: ReturnType<typeof setTimeout> | undefined;
 
         try {
@@ -359,6 +372,13 @@ export class PolicyContextBuilder {
     /**
      * Resolves all required context paths and returns a flat context object.
      * If any required path cannot be resolved, returns an error.
+     *
+     * Resolution is deliberately sequential and fail-fast: paths resolve in
+     * order and the first failure returns immediately, so later resolvers never
+     * run once one path fails. This trades the latency-hiding of parallel
+     * resolution for skipping downstream (potentially expensive) lookups on a
+     * doomed evaluation. It is a tested contract, not an oversight — flip it to
+     * `Promise.all` only if you also accept that every resolver always runs.
      */
     async build(
         requirements: readonly string[],

package/src/core/policies/context/context-resolver.ts

@@ -23,6 +23,11 @@ export interface ContextResolverResilienceOptions {
 /**
  * A resolver that knows how to produce a value for a specific context path.
  * Designed as async to allow future DB/API lookups without breaking the interface.
+ *
+ * Resolvers MUST be idempotent, side-effect-free reads. The builder's timeout
+ * is a race with no cancellation, so a timed-out resolver keeps running; with
+ * retry enabled it may also be invoked several times for one path. Anything but
+ * a pure lookup here risks duplicated effects.
  */
 export interface ContextValueResolver {
     readonly path: string;

package/src/core/policies/context/context-seed.ts

@@ -6,6 +6,17 @@ import type { SchoolId, TenantId } from "../policy-ids.js";
  * Seed data provided by the use case / caller.
  * Contains raw IDs and inputs that the context system will resolve into paths.
  * Each resolver is responsible for validating and extracting what it needs from fields.
+ *
+ * `tenantId`/`schoolId` are required on every seed, including evaluations scoped
+ * at TENANT or GLOBAL level. The `schoolId`/`SCHOOL` vocabulary is deliberately
+ * school-first: erp-core is a school ERP core, and a full-control copy targeting
+ * another domain is expected to rename these ids to its own leaf scope.
+ *
+ * `fields` is an open bag, but two keys are reserved by the pipeline and carry
+ * meaning beyond "just data":
+ * - `now` (a `Date`) pins the evaluation clock;
+ * - `asOf` (a `Date`) supplies the instant for `asOfSource: "CALLER_PROVIDED"`.
+ * See {@link EvaluateInput} and {@link PolicyAsOfResolver}.
  */
 export interface ContextSeed {
     readonly tenantId: TenantId;

package/src/core/policies/defs/in-memory-policy-definition-repo.ts

@@ -6,14 +6,12 @@ import type { PolicyDefinitionRepository } from "./policy-definition-repository.
 import { PolicyScopeMatcher } from "./policy-scope.js";
 
 export class InMemoryPolicyDefinitionRepository implements PolicyDefinitionRepository {
-    private readonly definitions: readonly PolicyDefinition[];
     private readonly definitionsByPolicyKey: ReadonlyMap<
         string,
         readonly PolicyDefinition[]
     >;
 
     constructor(definitions: readonly PolicyDefinition[]) {
-        this.definitions = definitions;
         this.definitionsByPolicyKey = definitions.reduce<
             Map<string, PolicyDefinition[]>
         >((index, definition) => {

package/src/core/policies/engines/parse-gate-payload.ts

@@ -8,6 +8,15 @@ export type GatePayloadParser = (
     payload: unknown,
 ) => ResultType<GatePayload, string>;
 
+// Versioning decision (deliberate asymmetry with compute):
+// Gate parsers are keyed by GATE ENGINE VERSION, not by `payloadSchemaVersion`.
+// A gate definition's `payloadSchemaVersion` therefore selects a catalog
+// variant but has NO effect on parsing — under one gate engine version there is
+// exactly one payload shape. Compute is the opposite: its parsers are keyed by
+// `payloadSchemaVersion` (see parse-compute-payload.ts), because a compute
+// engine version can host several payload schemas. If a second gate payload
+// schema under one engine version ever becomes necessary, migrate gate parsing
+// to be keyed by `payloadSchemaVersion` here to match compute.
 export class GatePayloadParserRegistry {
     private readonly parsers = new Map<number, GatePayloadParser>();
 

package/src/core/policies/engines/v1/condition-date-operands.ts

@@ -0,0 +1,112 @@
+// Pure helpers for treating condition operands as instants. Extracted from
+// condition-evaluator.ts to keep that file under the kit's size limit and to
+// isolate the (zod-free) date logic the ./abac subpath re-uses. Import the date
+// util directly (not the utils barrel): the barrel re-exports PolicyHashing,
+// whose node:crypto import would needlessly drag a Node-only API into the
+// zod-free ./abac subpath.
+import { PolicyDateUtils } from "../../utils/date.js";
+import { Result } from "../../../result/result.js";
+
+import type { ConditionOp } from "./condition-types.js";
+
+export type RelationalOperator = Extract<
+    ConditionOp,
+    "gt" | "gte" | "lt" | "lte"
+>;
+
+/**
+ * The one instant format condition date operands may use. Strict on purpose
+ * (UTC, milliseconds) so comparisons are unambiguous across time zones — and
+ * so a malformed operand fails loudly instead of comparing wrong.
+ */
+export const CANONICAL_UTC_DATE_FORMAT = "YYYY-MM-DDTHH:mm:ss.SSSZ";
+
+const ISO_8601_UTC_DATE_PATTERN =
+    /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+// A value that is clearly meant to be a date-time but isn't canonical UTC
+// (missing milliseconds, a non-UTC offset, a space separator…). Lets the
+// caller report a "malformed date" error instead of a misleading "not a
+// number" one.
+const ISO_8601_DATE_LIKE_PATTERN = /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}/;
+
+/**
+ * Parses a value used as a date operand:
+ * - `Result.ok(Date)` for a valid Date or a canonical ISO-8601 UTC string;
+ * - `Result.err` when it is date-shaped but malformed (invalid Date, or a
+ *   date-like string that isn't canonical UTC) — a configuration error worth
+ *   surfacing rather than silently treating as "not a date";
+ * - `null` when the value isn't date-shaped at all, so the caller can fall
+ *   through to a numeric comparison.
+ */
+export function parseComparableDate(
+    value: unknown,
+): Result<Date, string> | null {
+    if (value instanceof Date) {
+        return PolicyDateUtils.isValid(value)
+            ? Result.ok(value)
+            : Result.err("Invalid Date instance");
+    }
+
+    if (typeof value !== "string") {
+        return null;
+    }
+
+    if (ISO_8601_UTC_DATE_PATTERN.test(value)) {
+        const parsed = new Date(value);
+        if (
+            !PolicyDateUtils.isValid(parsed) ||
+            parsed.toISOString() !== value
+        ) {
+            return Result.err("Invalid ISO 8601 UTC date string");
+        }
+
+        return Result.ok(parsed);
+    }
+
+    if (ISO_8601_DATE_LIKE_PATTERN.test(value)) {
+        return Result.err(
+            `date operand must be canonical ISO 8601 UTC (${CANONICAL_UTC_DATE_FORMAT})`,
+        );
+    }
+
+    return null;
+}
+
+export function evaluateRelationalNumbers(
+    actual: number,
+    op: RelationalOperator,
+    expected: number,
+): boolean {
+    switch (op) {
+        case "gt":
+            return actual > expected;
+        case "gte":
+            return actual >= expected;
+        case "lt":
+            return actual < expected;
+        case "lte":
+            return actual <= expected;
+    }
+}
+
+export function containsInvalidDate(value: unknown): boolean {
+    if (value instanceof Date) {
+        return !PolicyDateUtils.isValid(value);
+    }
+    if (Array.isArray(value)) {
+        return value.some((item) => containsInvalidDate(item));
+    }
+    return false;
+}
+
+// Valid Dates become their ISO string so equality/set operators compare
+// instants instead of references; every other value passes through.
+export function normalizeDateOperand(value: unknown): unknown {
+    if (value instanceof Date) {
+        return value.toISOString();
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => normalizeDateOperand(item));
+    }
+    return value;
+}