@cullet/erp-core 1.3.0 → 1.5.0

package/src/core/abac/authorizer.ts

@@ -0,0 +1,108 @@
+import { type CoreConfig, coreConfig } from "../config/index.js";
+import { AuthorizationError } from "../errors/authorization-error.js";
+import { ConditionEvaluatorV1 } from "../policies/engines/v1/condition-evaluator.js";
+import { Result } from "../result/result.js";
+
+import type { AbacRequest } from "./abac-request.js";
+import { abacContext } from "./attributes.js";
+import { combine, type CombiningAlgorithm } from "./combining.js";
+import type { AbacPolicySet } from "./domain/policy-set.js";
+import type { AbacRule } from "./domain/rule.js";
+
+// ABAC reuses the gate engine's v1 condition matcher; the version stamps the
+// evaluation reports the shared reporter emits.
+const ENGINE_VERSION = 1;
+
+/** The successful decision returned by {@link AbacAuthorizer.authorize}. */
+interface AbacDecision {
+    /** The audited business action that was allowed. */
+    readonly action: string;
+    readonly effect: "PERMIT";
+    /** The id of the rule that permitted, or `"<default>"` when the set's default did. */
+    readonly matchedRule: string;
+    readonly algorithm: CombiningAlgorithm;
+    /** When the decision was made, ISO-8601. */
+    readonly grantedAtIso: string;
+}
+
+/**
+ * The pure ABAC decisor. Given an {@link AbacRequest} and an
+ * {@link AbacPolicySet}, it flattens the request's attributes into a context,
+ * matches each rule's condition with the gate engine's pure condition evaluator
+ * (reused, not reimplemented), resolves the effects through the set's combining
+ * algorithm, and returns a {@link Result} — never throwing, mirroring the
+ * "errors as values" contract of `RbacAuthorizer`/`GateEngineV1`.
+ *
+ * A denial maps to {@link AuthorizationError.policyDenied}, attributed to the
+ * deciding rule's `id`/`version`; a condition-evaluation failure (a missing
+ * attribute, a wrong-typed operand) fails closed as
+ * {@link AuthorizationError.forbidden}. Loading the dynamic attributes is the
+ * consumer's job (behind an `AbacAuthorizerPort` adapter); this class only decides.
+ */
+class AbacAuthorizer {
+    private readonly coreConfig: CoreConfig;
+
+    constructor(params: { readonly coreConfig?: CoreConfig } = {}) {
+        this.coreConfig = params.coreConfig ?? coreConfig;
+    }
+
+    authorize(
+        request: AbacRequest,
+        policies: AbacPolicySet,
+    ): Result<AbacDecision, AuthorizationError> {
+        const context = abacContext(request);
+        const evaluator = new ConditionEvaluatorV1(
+            context,
+            this.coreConfig.getConditionEvaluationOptions(ENGINE_VERSION),
+        );
+
+        const applicable: AbacRule[] = [];
+        for (const rule of policies.rules) {
+            const matched = evaluator.evaluate(rule.condition);
+            if (matched.isErr()) {
+                // Fail closed: a technical evaluation error is never a silent PERMIT.
+                return Result.err(
+                    AuthorizationError.forbidden({
+                        action: request.action,
+                        resource: request.resource,
+                        actor: { userId: request.actor.raw },
+                        details: matched.errorOrNull() ?? undefined,
+                    }),
+                );
+            }
+            if (matched.getOrThrow()) {
+                applicable.push(rule);
+            }
+        }
+
+        const { effect, decidingRule } = combine(
+            policies.algorithm,
+            applicable,
+            policies.defaultEffect,
+        );
+
+        if (effect === "PERMIT") {
+            return Result.ok({
+                action: request.action,
+                effect: "PERMIT",
+                matchedRule: decidingRule?.id ?? "<default>",
+                algorithm: policies.algorithm,
+                grantedAtIso: new Date().toISOString(),
+            });
+        }
+
+        return Result.err(
+            AuthorizationError.policyDenied({
+                policyId: decidingRule?.id ?? "<default-deny>",
+                policyVersion: decidingRule?.version ?? 0,
+                evaluatedAtIso: new Date().toISOString(),
+                action: request.action,
+                resource: request.resource,
+                actor: { userId: request.actor.raw },
+                reasonCode: decidingRule?.id,
+            }),
+        );
+    }
+}
+
+export { AbacAuthorizer, type AbacDecision };

package/src/core/abac/combining.ts

@@ -0,0 +1,63 @@
+import type { AbacRule, RuleEffect } from "./domain/rule.js";
+
+/**
+ * How an {@link AbacPolicySet} resolves several applicable rules into one effect.
+ *
+ * - `deny-overrides` (default, secure): any applicable DENY wins; otherwise the
+ *   first PERMIT; otherwise the set's default effect.
+ * - `permit-overrides`: any applicable PERMIT wins; otherwise the first DENY;
+ *   otherwise the default effect.
+ * - `first-applicable`: the effect of the first rule that matches; otherwise the
+ *   default effect.
+ */
+export type CombiningAlgorithm =
+    | "deny-overrides"
+    | "permit-overrides"
+    | "first-applicable";
+
+/** The resolved decision plus the rule (if any) that produced it. */
+export interface CombineResult {
+    readonly effect: RuleEffect;
+    readonly decidingRule?: AbacRule;
+}
+
+function firstWithEffect(
+    rules: readonly AbacRule[],
+    effect: RuleEffect,
+): AbacRule | undefined {
+    return rules.find((rule) => rule.effect === effect);
+}
+
+/**
+ * Applies `algorithm` to the already-matched `applicable` rules, falling back to
+ * `defaultEffect` when the algorithm reaches no rule-backed decision. Pure and
+ * total; the returned `decidingRule` is absent exactly when `defaultEffect` was
+ * used.
+ */
+export function combine(
+    algorithm: CombiningAlgorithm,
+    applicable: readonly AbacRule[],
+    defaultEffect: RuleEffect,
+): CombineResult {
+    switch (algorithm) {
+        case "deny-overrides": {
+            const deny = firstWithEffect(applicable, "DENY");
+            if (deny) return { effect: "DENY", decidingRule: deny };
+            const permit = firstWithEffect(applicable, "PERMIT");
+            if (permit) return { effect: "PERMIT", decidingRule: permit };
+            return { effect: defaultEffect };
+        }
+        case "permit-overrides": {
+            const permit = firstWithEffect(applicable, "PERMIT");
+            if (permit) return { effect: "PERMIT", decidingRule: permit };
+            const deny = firstWithEffect(applicable, "DENY");
+            if (deny) return { effect: "DENY", decidingRule: deny };
+            return { effect: defaultEffect };
+        }
+        case "first-applicable": {
+            const first = applicable[0];
+            if (first) return { effect: first.effect, decidingRule: first };
+            return { effect: defaultEffect };
+        }
+    }
+}

package/src/core/abac/composite-authorizer.ts

@@ -0,0 +1,45 @@
+import { Result } from "../result/result.js";
+import type { AbacAuthorizerPort } from "../application/ports/abac-authorizer.port.js";
+import type { AuthorizerPort } from "../application/ports/authorizer.port.js";
+import type { AuthorizationError } from "../errors/authorization-error.js";
+import type { AccessRequest } from "../rbac/access-request.js";
+
+import type { AbacAttributes } from "./abac-request.js";
+
+/**
+ * The request a {@link CompositeAuthorizer} accepts — one object that satisfies
+ * both the RBAC {@link AccessRequest} (its `required`/`scope`) and the ABAC
+ * request (its `attributes`).
+ */
+type CompositeAccessRequest = AccessRequest & {
+    readonly attributes: AbacAttributes;
+};
+
+/**
+ * Runs a coarse RBAC check first, then refines with ABAC — the standard hybrid
+ * "does the actor hold the capability, *and* do the attributes allow it here?"
+ * flow. Short-circuits with the RBAC denial when the actor is not even capable,
+ * so the boundary sees the most specific 403.
+ *
+ * Only the two port interfaces are referenced (both erased at runtime), so this
+ * pulls in no RBAC/ABAC engine code of its own — it just sequences the seams the
+ * consumer wires up.
+ */
+class CompositeAuthorizer {
+    constructor(
+        private readonly rbac: AuthorizerPort,
+        private readonly abac: AbacAuthorizerPort,
+    ) {}
+
+    async authorize(
+        request: CompositeAccessRequest,
+    ): Promise<Result<void, AuthorizationError>> {
+        const coarse = await this.rbac.authorize(request);
+        if (coarse.isErr()) {
+            return coarse;
+        }
+        return this.abac.authorize(request);
+    }
+}
+
+export { CompositeAuthorizer, type CompositeAccessRequest };

package/src/core/abac/domain/policy-set.ts

@@ -0,0 +1,52 @@
+import type { CombiningAlgorithm } from "../combining.js";
+
+import type { AbacRule, RuleEffect } from "./rule.js";
+
+/**
+ * An ordered collection of {@link AbacRule}s plus how to combine them
+ * ({@link CombiningAlgorithm}) and what to decide when no rule applies
+ * ({@link defaultEffect}). This is where ABAC goes beyond a single gate
+ * condition: several PERMIT/DENY rules resolved by an explicit algorithm.
+ *
+ * Closed by default — the combining algorithm defaults to `"deny-overrides"` and
+ * the default effect to `"DENY"`, so a request matching nothing is denied. A
+ * plain holder (not a value object); build through {@link of}.
+ */
+class AbacPolicySet {
+    private constructor(
+        private readonly _rules: readonly AbacRule[],
+        private readonly _algorithm: CombiningAlgorithm,
+        private readonly _defaultEffect: RuleEffect,
+    ) {
+        Object.freeze(this._rules);
+        Object.freeze(this);
+    }
+
+    static of(
+        rules: readonly AbacRule[],
+        options: {
+            readonly algorithm?: CombiningAlgorithm;
+            readonly defaultEffect?: RuleEffect;
+        } = {},
+    ): AbacPolicySet {
+        return new AbacPolicySet(
+            [...rules],
+            options.algorithm ?? "deny-overrides",
+            options.defaultEffect ?? "DENY",
+        );
+    }
+
+    get rules(): readonly AbacRule[] {
+        return this._rules;
+    }
+
+    get algorithm(): CombiningAlgorithm {
+        return this._algorithm;
+    }
+
+    get defaultEffect(): RuleEffect {
+        return this._defaultEffect;
+    }
+}
+
+export { AbacPolicySet };

package/src/core/abac/domain/rule.ts

@@ -0,0 +1,197 @@
+import { ValidationCode } from "../../exceptions/validation-code.js";
+import { InvalidValueException } from "../../exceptions/validation-exception.js";
+import { ValidationField } from "../../exceptions/validation-field.js";
+import { ValueObject } from "../../domain/value-object.js";
+import type {
+    ConditionNode,
+    ConditionOp,
+} from "../../policies/engines/v1/condition-types.js";
+
+/** Whether a matching {@link AbacRule} permits or denies the action. */
+type RuleEffect = "PERMIT" | "DENY";
+
+/**
+ * The serializable shape of a rule: a stable `id`/`version` (surfaced on a
+ * denial as `policyId`/`policyVersion`), the {@link RuleEffect}, and the
+ * {@link ConditionNode} that decides whether the rule applies to a request's
+ * flattened attributes.
+ */
+type AbacRuleProps = {
+    readonly id: string;
+    readonly version: number;
+    readonly effect: RuleEffect;
+    readonly condition: ConditionNode;
+    readonly description?: string;
+};
+
+const RULE_FIELD = ValidationField.of("abacRule");
+
+const CONDITION_OPS = new Set<ConditionOp>([
+    "eq",
+    "neq",
+    "gt",
+    "gte",
+    "lt",
+    "lte",
+    "in",
+    "notIn",
+    "isNull",
+    "isNotNull",
+]);
+
+const RULE_EFFECTS = new Set<RuleEffect>(["PERMIT", "DENY"]);
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * A single attribute-based rule: an {@link RuleEffect} that takes hold when its
+ * {@link ConditionNode} matches the request's flattened attributes. The
+ * condition reuses the gate/compute condition DSL (`{ field, op, value }` leaves
+ * combined with `and`/`or`/`not`), so a consumer learns one condition language
+ * across the whole kit.
+ *
+ * A zod-free value object: it validates its own shape on construction (throwing
+ * {@link InvalidValueException}) and is deep-frozen thereafter. Because rules are
+ * authored in TypeScript — trusted data, not untrusted JSON — the structural
+ * check is a hand-rolled walk of the condition tree rather than a schema parse.
+ * Build one through {@link of}; the constructor is private.
+ */
+class AbacRule extends ValueObject<AbacRuleProps, AbacRuleProps> {
+    private constructor(props: AbacRuleProps) {
+        super(props);
+        this.finalize();
+    }
+
+    /**
+     * Builds a rule, validating that `id` is non-blank, `version` is an integer
+     * ≥ 1, `effect` is `"PERMIT"`/`"DENY"`, and `condition` is a well-formed
+     * condition node. Throws {@link InvalidValueException} otherwise.
+     */
+    static of(props: AbacRuleProps): AbacRule {
+        if (typeof props.id !== "string" || props.id.trim().length === 0) {
+            throw new InvalidValueException(
+                RULE_FIELD.nested("id"),
+                ValidationCode.BLANK,
+                `abac rule id must be a non-empty string, got "${props.id}"`,
+            );
+        }
+
+        if (!Number.isInteger(props.version) || props.version < 1) {
+            throw new InvalidValueException(
+                RULE_FIELD.nested("version"),
+                ValidationCode.OUT_OF_RANGE,
+                `abac rule version must be an integer >= 1, got "${props.version}"`,
+            );
+        }
+
+        if (!RULE_EFFECTS.has(props.effect)) {
+            throw new InvalidValueException(
+                RULE_FIELD.nested("effect"),
+                ValidationCode.INVALID_FORMAT,
+                `abac rule effect must be "PERMIT" or "DENY", got "${String(props.effect)}"`,
+            );
+        }
+
+        AbacRule.assertConditionShape(props.condition);
+
+        return new AbacRule(props);
+    }
+
+    // Mirrors what the shared condition evaluator would reject at eval time
+    // (empty and/or nodes, malformed leaves) but fails fast at construction.
+    private static assertConditionShape(node: unknown): void {
+        if (!isPlainObject(node)) {
+            AbacRule.rejectCondition(
+                "abac rule condition must be a leaf { field, op } or an { and | or | not } node",
+            );
+        }
+
+        if ("and" in node || "or" in node) {
+            const key = "and" in node ? "and" : "or";
+            const children = node[key];
+            if (!Array.isArray(children) || children.length === 0) {
+                AbacRule.rejectCondition(
+                    `abac rule "${key}" node must hold a non-empty array of child conditions`,
+                );
+            }
+            for (const child of children) {
+                AbacRule.assertConditionShape(child);
+            }
+            return;
+        }
+
+        if ("not" in node) {
+            AbacRule.assertConditionShape(node.not);
+            return;
+        }
+
+        if ("field" in node && "op" in node) {
+            if (
+                typeof node.field !== "string" ||
+                node.field.trim().length === 0
+            ) {
+                AbacRule.rejectCondition(
+                    `abac rule condition leaf "field" must be a non-empty string, got "${String(node.field)}"`,
+                );
+            }
+            if (
+                typeof node.op !== "string" ||
+                !CONDITION_OPS.has(node.op as ConditionOp)
+            ) {
+                AbacRule.rejectCondition(
+                    `abac rule condition leaf "op" is not a supported operator, got "${String(node.op)}"`,
+                );
+            }
+            return;
+        }
+
+        AbacRule.rejectCondition(
+            "abac rule condition must be a leaf { field, op } or an { and | or | not } node",
+        );
+    }
+
+    private static rejectCondition(message: string): never {
+        throw new InvalidValueException(
+            RULE_FIELD.nested("condition"),
+            ValidationCode.INVALID_FORMAT,
+            message,
+        );
+    }
+
+    get id(): string {
+        return this.value.id;
+    }
+
+    get version(): number {
+        return this.value.version;
+    }
+
+    get effect(): RuleEffect {
+        return this.value.effect;
+    }
+
+    /** The condition tree evaluated against a request's flattened attributes. */
+    get condition(): ConditionNode {
+        return this.value.condition as ConditionNode;
+    }
+
+    get description(): string | undefined {
+        return this.value.description;
+    }
+
+    toPrimitive(): AbacRuleProps {
+        return {
+            id: this.value.id,
+            version: this.value.version,
+            effect: this.value.effect,
+            condition: this.value.condition as ConditionNode,
+            ...(this.value.description !== undefined
+                ? { description: this.value.description }
+                : {}),
+        };
+    }
+}
+
+export { AbacRule, type AbacRuleProps, type RuleEffect };

package/src/core/abac/index.ts

@@ -0,0 +1,21 @@
+// Barrel for the zod-free ABAC module: the pure rule/policy-set primitives, the
+// combining algorithms, the attribute→context flattening, the pure decisor, the
+// optional RBAC+ABAC composite, and the AbacAuthorizerPort seam (which physically
+// lives under application/ports/ but is surfaced here as the ABAC public home).
+
+export type { AbacAuthorizerPort } from "../application/ports/abac-authorizer.port.js";
+
+export type { AbacAttributes, AbacRequest } from "./abac-request.js";
+export { abacContext } from "./attributes.js";
+export { AbacAuthorizer, type AbacDecision } from "./authorizer.js";
+export type { CombiningAlgorithm } from "./combining.js";
+export {
+    type CompositeAccessRequest,
+    CompositeAuthorizer,
+} from "./composite-authorizer.js";
+export { AbacPolicySet } from "./domain/policy-set.js";
+export {
+    AbacRule,
+    type AbacRuleProps,
+    type RuleEffect,
+} from "./domain/rule.js";

package/src/core/application/commands/requested-by.ts

@@ -1,10 +1,12 @@
 import { ValidationCode } from "../../exceptions/validation-code.js";
 import { InvalidValueException } from "../../exceptions/validation-exception.js";
 import { ValidationField } from "../../exceptions/validation-field.js";
+import { UUID_PATTERN } from "../../shared/uuid.js";
 
 // Identifies who triggered a Command.
 // Two valid formats:
-//   - Human user: UUID v4 (e.g.: "550e8400-e29b-41d4-a716-446655440000")
+//   - Human user: canonical RFC-4122 UUID, versions 1–5 — the same pattern
+//     `UuidIdentifier` enforces (e.g.: "550e8400-e29b-41d4-a716-446655440000")
 //   - System identity: "system:<job>" where <job> is [a-z][a-z0-9]*(-[a-z0-9]+)*
 //     (e.g.: "system:late-fee-job", "system:email-sender")
 //
@@ -15,9 +17,6 @@ type RequestedByKind = "user" | "system";
 
 const REQUESTED_BY_FIELD = ValidationField.of("requestedBy");
 
-const UUID_PATTERN =
-    /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-
 // system:<job> where <job> starts with a lowercase letter and may have hyphens between segments
 const SYSTEM_IDENTITY_PATTERN = /^system:[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
 

package/src/core/application/ports/abac-authorizer.port.ts

@@ -0,0 +1,20 @@
+import type { AbacRequest } from "../../abac/abac-request.js";
+import type { AuthorizationError } from "../../errors/authorization-error.js";
+import type { Result } from "../../result/result.js";
+
+/**
+ * The seam an application layer injects to authorize an action by attributes —
+ * symmetric to {@link AuthorizerPort} (RBAC). The use case depends only on this
+ * contract; an adapter in the consumer's stack resolves the dynamic attributes
+ * (resource state, environment, RBAC facts) and delegates the decision to the
+ * pure `AbacAuthorizer`.
+ *
+ * Returns the decision as a {@link Result}: `ok(void)` when permitted, or
+ * `err(AuthorizationError)` carrying `reason: "policy_denied"` (or `"forbidden"`
+ * on a fail-closed evaluation error) that the HTTP boundary maps to a 403.
+ */
+interface AbacAuthorizerPort {
+    authorize(request: AbacRequest): Promise<Result<void, AuthorizationError>>;
+}
+
+export type { AbacAuthorizerPort };

package/src/core/application/ports/authorizer.port.ts

@@ -0,0 +1,22 @@
+import type { AuthorizationError } from "../../errors/authorization-error.js";
+import type { AccessRequest } from "../../rbac/access-request.js";
+import type { Result } from "../../result/result.js";
+
+/**
+ * The seam an application layer injects to authorize an action — symmetric to
+ * {@link PolicyPort}. The use case depends only on this contract; an adapter in
+ * the consumer's stack loads the actor's grants (from its own store) and
+ * delegates the decision to the pure `RbacAuthorizer`.
+ *
+ * Returns the decision as a {@link Result}: `ok(void)` when allowed, or
+ * `err(AuthorizationError)` carrying the discriminated `reason` the HTTP
+ * boundary maps to a 403. Promised here under `[extension-points]` in
+ * KIT_CONTEXT.md.
+ */
+interface AuthorizerPort {
+    authorize(
+        request: AccessRequest,
+    ): Promise<Result<void, AuthorizationError>>;
+}
+
+export type { AuthorizerPort };

package/src/core/application/queries/query.ts

@@ -44,7 +44,12 @@ abstract class Query<
     Data extends QueryOutput = never,
     Failure = AppError,
 > extends UseCase<Input, Result<Data, Failure>> {
-    protected cacheStrategy(): CacheStrategy {
+    /**
+     * Declares how infrastructure should cache this query's result. Public so
+     * a caching adapter can actually read it off the instance; overrides must
+     * stay public.
+     */
+    public cacheStrategy(): CacheStrategy {
         return { kind: "NO_CACHE" };
     }
 }

package/src/core/application/use-case.ts

@@ -34,7 +34,7 @@ abstract class UseCase<
     declare public static readonly CONTRACT_VERSION: ContractVersion;
 
     public get contractVersion(): ContractVersion {
-        return UseCase.CONTRACT_VERSION;
+        return (this.constructor as typeof UseCase).CONTRACT_VERSION;
     }
 
     /**

package/src/core/domain/entity.ts

@@ -112,7 +112,7 @@ abstract class Entity<TIdentifier> {
      * an older shape.
      */
     public get contractVersion(): ContractVersion {
-        return Entity.CONTRACT_VERSION;
+        return (this.constructor as typeof Entity).CONTRACT_VERSION;
     }
 
     /**

package/src/core/domain/uuid-identifier.ts

@@ -1,13 +1,6 @@
+import { UUID_PATTERN } from "../shared/uuid.js";
 import { ValueObject } from "./value-object.js";
 
-/**
- * Canonical RFC-4122 UUID (versions 1–5), matched case-insensitively. Declared
- * once here so the dozens of typed identifiers a domain accumulates never have
- * to re-state the pattern.
- */
-const UUID_PATTERN =
-    /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
-
 /**
  * Base class for UUID-backed identity value objects.
  *

package/src/core/domain/value-object.ts

@@ -1,5 +1,6 @@
 import { PluginManager } from "../plugins/index.js";
 import { type DeepReadonly, makeImmutable } from "../shared/immutable.js";
+import { stableStringify } from "../shared/stable-stringify.js";
 import { type ContractVersion, version } from "../versioning/version.js";
 
 /**
@@ -28,6 +29,12 @@ type ValueObjectPluginContract = {
  * any risk of a consumer mutating shared state. Subclasses seal the instance
  * itself with {@link finalize} once their own fields are set.
  *
+ * One exception: nested `Date` instances are cloned but NOT frozen —
+ * `Object.freeze` does not block `setTime`/`setFullYear`, so a consumer of
+ * `value` can still mutate an inner `Date` in place. Store instants as ISO
+ * strings or epoch timestamps in the wrapped state (converting to `Date` only
+ * in an accessor) when that guarantee matters.
+ *
  * @typeParam T - The shape of the wrapped data.
  * @typeParam P - The primitive form produced by {@link toPrimitive} / {@link toJSON}.
  */
@@ -61,7 +68,7 @@ abstract class ValueObject<T, P> {
      * `@version` decorator — used to detect state persisted under an older shape.
      */
     public get contractVersion(): ContractVersion {
-        return ValueObject.CONTRACT_VERSION;
+        return (this.constructor as typeof ValueObject).CONTRACT_VERSION;
     }
 
     /**
@@ -93,13 +100,15 @@ abstract class ValueObject<T, P> {
      * same data are considered equal.
      *
      * Delegates to the registered equality {@link plugins}; with no plugin
-     * registered it falls back to comparing the serialized wrapped `value`.
+     * registered it falls back to comparing the serialized wrapped `value`,
+     * with object keys sorted so insertion order (e.g. code-built vs
+     * JSON-rehydrated) never affects the result.
      * Subclasses may still override for a faster or domain-specific comparison.
      */
     public equals(other: this): boolean {
         return ValueObject.plugins.invoke("equals", [this, other], {
             fallback: (a, b) =>
-                JSON.stringify(a.value) === JSON.stringify(b.value),
+                stableStringify(a.value) === stableStringify(b.value),
         });
     }