@cullet/erp-core 1.4.0 → 2.0.0

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

@@ -23,11 +23,7 @@ import { PolicyResolver } from "../resolver/index.js";
 import { Result } from "../../result/result.js";
 import { isValidDate } from "../../shared/temporal-guards.js";
 
-import type {
-    PolicyEvent,
-    PolicyReporter,
-} from "../../config/policy-reporter.js";
-import { SilentPolicyReporter } from "../../config/silent-policy-reporter.js";
+import { type CoreConfig, coreConfig } from "../../config/index.js";
 
 import {
     PolicyEvaluationErrors,
@@ -42,6 +38,21 @@ import {
  * `contextVersion` pins which context schema applies, and `seed` carries the
  * raw facts the context builder expands. `decisionId` is the caller's
  * idempotency/audit handle, echoed back on the result.
+ *
+ * `contextVersion` is a caller assertion, not a proof: it filters which
+ * definitions are compatible, but nothing checks that the context actually
+ * built matches the declared version — supplying the right number is the
+ * caller's contract.
+ *
+ * Two `seed.fields` keys are reserved and change what "now" means for this
+ * evaluation:
+ * - `now` (a `Date`) pins the evaluation clock — it feeds `evaluatedAt`, the
+ *   `asOf` derivation, and therefore which effective-dated definitions are in
+ *   force. Leave it unset to use wall-clock time.
+ * - `asOf` (a `Date`) is consumed when the policy's `asOfSource` is
+ *   `CALLER_PROVIDED` (see {@link PolicyAsOfResolver}).
+ * Whoever assembles `fields` from untrusted input owns the consequence: a
+ * caller who can set these keys can shift which policy version is selected.
  */
 export interface EvaluateInput {
     readonly decisionId: PolicyDecisionId;
@@ -52,14 +63,13 @@ export interface EvaluateInput {
 }
 
 /**
- * Cross-cutting knobs for a {@link PolicyService}: how the as-of instant is
- * derived ({@link asOf}) and where evaluation telemetry is sent
- * ({@link reporter}). Both are optional; the service defaults to a silent
- * reporter so telemetry is opt-in.
+ * Cross-cutting knobs for a {@link PolicyService}: today just how the as-of
+ * instant is derived ({@link asOf}). Telemetry is not configured here — it
+ * flows through the injected {@link CoreConfig}, the core's single
+ * observability seam, so a host wires reporting in one place.
  */
 export interface PolicyServiceOptions {
     readonly asOf?: DeriveAsOfOptions;
-    readonly reporter?: PolicyReporter;
 }
 
 /**
@@ -75,6 +85,12 @@ export interface PolicyServiceParams {
     readonly resolver: PolicyResolver;
     readonly gateEngines: GateEngineRegistry;
     readonly computeRegistry: ComputeRegistry;
+    /**
+     * The observability seam telemetry is emitted through. Defaults to the
+     * shared {@link coreConfig} singleton; inject an isolated instance for
+     * tests or multi-tenant hosts.
+     */
+    readonly coreConfig?: CoreConfig;
     readonly options?: PolicyServiceOptions;
 }
 
@@ -89,8 +105,11 @@ export type { PolicyEvaluationError } from "./policy-evaluation-error.js";
  * The full record of one successful evaluation. Beyond the business
  * {@link decision}, it pins the exact definition that produced it — id, key,
  * version, payload hash, and engine version — together with the `asOf` instant
- * the policy was selected for and the wall-clock `evaluatedAt`. That provenance
- * is what makes a decision reproducible and auditable after the fact.
+ * the policy was selected for and `evaluatedAt`, the instant evaluation ran at.
+ * `evaluatedAt` is wall-clock time unless the caller pinned it via
+ * `seed.fields.now` (see {@link EvaluateInput}), in which case it echoes that.
+ * That provenance is what makes a decision reproducible and auditable after the
+ * fact.
  */
 export interface PolicyEvaluationResult {
     readonly decisionId: PolicyDecisionId;
@@ -130,7 +149,7 @@ interface ResolvedPolicyCandidate {
  * evaluation — which keeps observability strictly side-band.
  */
 export class PolicyService {
-    readonly #reporter: PolicyReporter;
+    private readonly coreConfig: CoreConfig;
     private readonly catalog: PolicyCatalog;
     private readonly contextBuilder: PolicyContextBuilder;
     private readonly defRepo: PolicyDefinitionRepository;
@@ -147,15 +166,7 @@ export class PolicyService {
         this.gateEngines = params.gateEngines;
         this.computeRegistry = params.computeRegistry;
         this.options = params.options ?? {};
-        this.#reporter = this.options.reporter ?? new SilentPolicyReporter();
-    }
-
-    #reportSafely(event: PolicyEvent): void {
-        try {
-            this.#reporter.report(event);
-        } catch {
-            // Falhas de telemetria nao podem interromper a avaliacao de politicas.
-        }
+        this.coreConfig = params.coreConfig ?? coreConfig;
     }
 
     private resolveEvaluationNow(seed: ContextSeed): Result<Date, string> {
@@ -192,10 +203,10 @@ export class PolicyService {
     async evaluate(
         input: EvaluateInput,
     ): Promise<Result<PolicyEvaluationResult, PolicyEvaluationError>> {
-        const result = await this.#evaluate(input);
+        const result = await this.runEvaluation(input);
         if (result.isErr()) {
             const error = result.errorOrNull()!;
-            this.#reportSafely({
+            this.coreConfig.reportSafely({
                 kind: "policy-evaluation-failed",
                 level: "error",
                 policyKey: "policyKey" in error ? error.policyKey : undefined,
@@ -206,7 +217,7 @@ export class PolicyService {
             });
         } else {
             const ok = result.getOrNull()!;
-            this.#reportSafely({
+            this.coreConfig.reportSafely({
                 kind: "policy-evaluation-completed",
                 level: "info",
                 policyKey: ok.ref.policyKey,
@@ -218,7 +229,7 @@ export class PolicyService {
         return result;
     }
 
-    async #evaluate(
+    private async runEvaluation(
         input: EvaluateInput,
     ): Promise<Result<PolicyEvaluationResult, PolicyEvaluationError>> {
         const seedResult = ContextSeedValidator.validate(input.seed);
@@ -233,7 +244,7 @@ export class PolicyService {
         }
         const seed = seedResult.getOrNull()!;
 
-        const catalogFamilyResult = this.#resolveCatalogFamily(input.policyKey);
+        const catalogFamilyResult = this.resolveCatalogFamily(input.policyKey);
         if (catalogFamilyResult.isErr()) {
             return Result.err(catalogFamilyResult.errorOrNull()!);
         }
@@ -269,7 +280,7 @@ export class PolicyService {
         }
         const asOf = asOfResult.getOrNull()!;
 
-        const definitionResult = this.#findCandidates(
+        const definitionResult = this.findCandidates(
             policyKey,
             familyEntry.kind,
             asOf,
@@ -283,7 +294,7 @@ export class PolicyService {
             catalogEntry: versionedCatalogEntry,
         } = definitionResult.getOrNull()!;
 
-        this.#reportSafely({
+        this.coreConfig.reportSafely({
             kind: "policy-resolution",
             level: "info",
             policyKey,
@@ -311,7 +322,7 @@ export class PolicyService {
         }
         const context = ctxResult.getOrNull()!;
 
-        const decisionResult = this.#executeEngine(
+        const decisionResult = this.executeEngine(
             policyKey,
             policyDefinition,
             context,
@@ -347,7 +358,7 @@ export class PolicyService {
         return Result.ok(result);
     }
 
-    #resolveCatalogVariant(
+    private resolveCatalogVariant(
         definition: PolicyDefinition,
     ): Result<PolicyCatalogEntry, string> {
         return this.catalog.getVersioned({
@@ -362,7 +373,7 @@ export class PolicyService {
         });
     }
 
-    #resolveCatalogFamily(
+    private resolveCatalogFamily(
         rawKey: string,
     ): Result<
         { key: string; family: readonly PolicyCatalogEntry[] },
@@ -395,7 +406,7 @@ export class PolicyService {
         });
     }
 
-    #findCandidates(
+    private findCandidates(
         policyKey: string,
         policyKind: PolicyCatalogEntry["kind"],
         asOf: Date,
@@ -420,7 +431,7 @@ export class PolicyService {
         >();
 
         for (const candidate of candidates) {
-            const compatibilityResult = this.#resolveCatalogVariant(candidate);
+            const compatibilityResult = this.resolveCatalogVariant(candidate);
             if (compatibilityResult.isErr()) {
                 incompatibleVariantErrorsByDefinitionId.set(
                     candidate.id,
@@ -503,7 +514,7 @@ export class PolicyService {
         return Result.ok(resolvedCandidate);
     }
 
-    #executeEngine(
+    private executeEngine(
         policyKey: string,
         definition: PolicyDefinition,
         context: PolicyContext,

package/src/core/policies/utils/hash.ts

@@ -1,5 +1,5 @@
-import { sha256Hex, stableStringify } from "../../shared/hashing.js";
-import { isValidDate } from "../../shared/temporal-guards.js";
+import { sha256Hex } from "../../shared/hashing.js";
+import { canonicalStringify } from "../../shared/stable-stringify.js";
 
 /**
  * Produces a deterministic SHA-256 hex digest of a canonical JSON representation.
@@ -7,6 +7,8 @@ import { isValidDate } from "../../shared/temporal-guards.js";
  * Array item order is preserved on purpose; callers that treat arrays as sets
  * must normalize or sort them before hashing.
  *
+ * The strict canonical form is owned by `shared/stable-stringify`
+ * ({@link canonicalStringify}); this class just composes it with SHA-256.
  * Values that JSON.stringify would silently drop or coerce (undefined,
  * non-finite numbers, functions, symbols, bigint) are rejected up-front to
  * prevent semantically different payloads from collapsing to the same hash.
@@ -16,74 +18,8 @@ export class PolicyHashing {
         return sha256Hex(input);
     }
 
-    private static assertHashable(
-        value: unknown,
-        path: string,
-        seen: WeakSet<object>,
-    ): void {
-        if (value === null) {
-            return;
-        }
-
-        const type = typeof value;
-
-        if (type === "undefined") {
-            throw new TypeError(
-                `canonicalJson does not accept undefined values (at ${path})`,
-            );
-        }
-
-        if (type === "number" && !Number.isFinite(value)) {
-            throw new TypeError(
-                `canonicalJson does not accept non-finite numbers (at ${path}, value: ${String(value)})`,
-            );
-        }
-
-        if (type === "bigint" || type === "function" || type === "symbol") {
-            throw new TypeError(
-                `canonicalJson does not accept ${type} values (at ${path})`,
-            );
-        }
-
-        if (type !== "object") {
-            return;
-        }
-
-        if (value instanceof Date) {
-            if (!isValidDate(value)) {
-                throw new TypeError(
-                    `canonicalJson does not accept Invalid Date (at ${path})`,
-                );
-            }
-            return;
-        }
-
-        if (seen.has(value as object)) {
-            throw new TypeError(
-                `canonicalJson does not accept circular references (at ${path})`,
-            );
-        }
-        seen.add(value as object);
-
-        if (Array.isArray(value)) {
-            value.forEach((item, index) => {
-                PolicyHashing.assertHashable(item, `${path}[${index}]`, seen);
-            });
-        } else {
-            for (const [key, nested] of Object.entries(
-                value as Record<string, unknown>,
-            )) {
-                PolicyHashing.assertHashable(nested, `${path}.${key}`, seen);
-            }
-        }
-
-        seen.delete(value as object);
-    }
-
     static canonicalJson(value: unknown): string {
-        PolicyHashing.assertHashable(value, "$", new WeakSet<object>());
-
-        return stableStringify(value);
+        return canonicalStringify(value);
     }
 
     static computePayloadHash(

package/src/core/policies/utils/result.ts

@@ -1,4 +1,4 @@
 // Re-export the core Result class.
 // The policies module uses Result<T, string> as its standard Result type.
 
-export { Err, Ok, Result } from "../../result/result.js";
+export { Err, Ok, Result } from "../../result/index.js";

package/src/core/rbac/access-request.ts

@@ -22,10 +22,20 @@ interface AccessRequest {
      */
     readonly required: Permission;
 
-    /** The target resource, identified without leaking its payload. */
+    /**
+     * The target resource, identified without leaking its payload. Carried for
+     * audit metadata only — the RBAC decisor does **not** check it. Per-resource
+     * ownership (this actor may cancel *this* order) is an ABAC/policy concern,
+     * not a role/permission one.
+     */
     readonly resource?: { readonly type: string; readonly id?: string };
 
-    /** The scope the resource lives in, e.g. `Scope.of("school:123")`. */
+    /**
+     * The scope the resource lives in, e.g. `Scope.of("school:123")`. Asking in
+     * the global scope (`Scope.global()`) means "may I do this *everywhere*?" and
+     * so requires a globally-scoped grant — it is **not** "in any scope I happen
+     * to hold". Ask about a concrete scope to check a bounded grant.
+     */
     readonly scope: Scope;
 }
 

package/src/core/rbac/authorizer.ts

@@ -36,6 +36,13 @@ class RbacAuthorizer {
      * 3. grants the permission but not in scope → `out_of_scope`;
      * 4. otherwise → ALLOW (`Result.ok`).
      *
+     * ALLOW is intentionally silent: `Result.ok(undefined)` carries no trace of
+     * *which* grant or role decided it. Denials are rich (see the metadata
+     * below) because they need to explain themselves; an allow does not. When an
+     * ERP needs a "who allowed this, and why" trail, that is the adapter's job —
+     * reconstruct it from the grants it loaded, or gate on `PermissionSet` before
+     * calling. Keeping the decisor's allow-path pure is the deliberate trade.
+     *
      * @throws {@link InvalidValueException} when `request.required` is a wildcard
      *   permission (only *granted* permissions may wildcard, never the *required*
      *   one).
@@ -59,7 +66,7 @@ class RbacAuthorizer {
         const metadata = {
             action: request.action,
             resource: request.resource,
-            actor: { userId: request.actor.raw },
+            actor: { actorId: request.actor.raw },
             required,
         };
 

package/src/core/rbac/domain/role.ts

@@ -83,6 +83,26 @@ class Role extends ValueObject<RoleProps, RoleProps> {
         return this._permissions;
     }
 
+    /**
+     * Two roles are equal when they share a name and the same *set* of
+     * permissions. Order-insensitive on purpose: a role is a bundle, not a
+     * sequence, so `Role.of("cashier", [read, cancel])` equals
+     * `Role.of("cashier", [cancel, read])`. Overrides the base
+     * {@link ValueObject.equals}, whose stable-stringify keeps array order and
+     * would call those two roles different. The stored order (and thus
+     * {@link permissions}/{@link toPrimitive}) is still first-seen; only the
+     * comparison sorts.
+     */
+    override equals(other: this): boolean {
+        if (this.value.name !== other.value.name) return false;
+        const mine = [...this.value.permissions].sort();
+        const theirs = [...other.value.permissions].sort();
+        return (
+            mine.length === theirs.length &&
+            mine.every((permission, index) => permission === theirs[index])
+        );
+    }
+
     /** Whether any permission in this role {@link Permission.implies | implies} `required`. */
     grants(required: Permission): boolean {
         return this._permissions.some((permission) =>

package/src/core/rbac/domain/scope.ts

@@ -29,7 +29,12 @@ class Scope extends ValueObject<ScopeProps, string> {
         this.finalize();
     }
 
-    /** Validates `"type:id"` or the global `"*"`, throwing on anything else. */
+    /**
+     * Validates `"type:id"` or the global `"*"`, throwing on anything else.
+     * `Scope.of("*")` is accepted and is equivalent to {@link Scope.global} —
+     * prefer `global()` at call-sites for intent, `of("*")` when rehydrating a
+     * stored string.
+     */
     static of(raw: string): Scope {
         if (typeof raw !== "string" || raw.trim().length === 0) {
             throw new InvalidValueException(

package/src/core/result/index.ts

@@ -0,0 +1,5 @@
+// Barrel for the result module — single source of truth for what it exports.
+// Result = technical success/failure; Outcome = business decision.
+
+export { Err, Ok, Result } from "./result.js";
+export { type CommonOutcomeStatus, Outcome } from "./outcome.js";

package/src/core/result/outcome.ts

@@ -1,5 +1,3 @@
-// core/domain/outcome.ts
-
 import { InvariantViolationException } from "../exceptions/invariant-violation-exception.js";
 
 /**
@@ -59,32 +57,32 @@ export class Outcome<S extends string, D = undefined> {
         data: D,
         reason?: string,
     ): Outcome<"APPROVED", D> {
-        return new Outcome("APPROVED", data, reason, Object.freeze({}));
+        return Outcome.of("APPROVED", data, reason);
     }
 
     static rejected<D = undefined>(
         data: D,
         reason: string,
     ): Outcome<"REJECTED", D> {
-        return new Outcome("REJECTED", data, reason, Object.freeze({}));
+        return Outcome.of("REJECTED", data, reason);
     }
 
     static noOp<D = undefined>(data: D, reason?: string): Outcome<"NO_OP", D> {
-        return new Outcome("NO_OP", data, reason, Object.freeze({}));
+        return Outcome.of("NO_OP", data, reason);
     }
 
     static deferred<D = undefined>(
         data: D,
         reason: string,
     ): Outcome<"DEFERRED", D> {
-        return new Outcome("DEFERRED", data, reason, Object.freeze({}));
+        return Outcome.of("DEFERRED", data, reason);
     }
 
     static requiresReview<D = undefined>(
         data: D,
         reason: string,
     ): Outcome<"REQUIRES_REVIEW", D> {
-        return new Outcome("REQUIRES_REVIEW", data, reason, Object.freeze({}));
+        return Outcome.of("REQUIRES_REVIEW", data, reason);
     }
 
     // ─── Type narrowing ────────────────────────────────────────────────

package/src/core/result/result.ts

@@ -41,6 +41,9 @@ export abstract class Result<T, E> {
 
     /**
      * Returns the value when this is success, or null when this is an error.
+     *
+     * Note: an `Ok(null)` also returns `null`, indistinguishable from an `Err`.
+     * Use `match`/`isOk` when that distinction matters.
      */
     getOrNull(): T | null {
         return this.match({
@@ -66,13 +69,15 @@ export abstract class Result<T, E> {
         return this.match({
             ok: (value) => value,
             err: (error) => {
-                throw error instanceof Error ? error : new Error(String(error));
+                throw toError(error);
             },
         });
     }
 
     /**
      * Transforms the success value using the provided function. Keeps the error when this is a failure.
+     *
+     * Exceptions thrown by `transform` propagate; they are not captured into an `Err`.
      */
     map<R>(transform: (value: T) => R): Result<R, E> {
         return this.match<Result<R, E>>({
@@ -85,6 +90,8 @@ export abstract class Result<T, E> {
 
     /**
      * Transforms the error using the provided function. Keeps the value when this is a success.
+     *
+     * Exceptions thrown by `transform` propagate; they are not captured into an `Err`.
      */
     mapError<F>(transform: (error: E) => F): Result<T, F> {
         return this.match<Result<T, F>>({
@@ -96,6 +103,8 @@ export abstract class Result<T, E> {
 
     /**
      * Chains another operation that returns a Result when this result is a success.
+     *
+     * Exceptions thrown by `transform` propagate; they are not captured into an `Err`.
      */
     flatMap<R>(transform: (value: T) => Result<R, E>): Result<R, E> {
         return this.match<Result<R, E>>({
@@ -107,6 +116,9 @@ export abstract class Result<T, E> {
 
 /**
  * Success variant of Result.
+ *
+ * The instance is frozen, but the freeze is shallow: a contained mutable
+ * object is not frozen.
  */
 export class Ok<T> extends Result<T, never> {
     public readonly value: T;
@@ -154,3 +166,24 @@ export class Err<E> extends Result<never, E> {
         return handlers.err(this.error);
     }
 }
+
+/**
+ * Coerces an arbitrary error value into an Error for `getOrThrow`, preserving
+ * the original structured payload as `cause` so nothing is lost when `E` is a
+ * plain object/DTO rather than an Error.
+ */
+function toError(error: unknown): Error {
+    if (error instanceof Error) return error;
+    if (typeof error === "string") return new Error(error);
+    let message: string | undefined;
+    try {
+        message = JSON.stringify(error);
+    } catch {
+        // circular / BigInt / etc.
+    }
+    const wrapped = new Error(message ?? String(error));
+    // Attach the original payload as `cause` (assigned, not passed to the
+    // ES2022 constructor option, to stay within the ES2020 lib target).
+    (wrapped as Error & { cause?: unknown }).cause = error;
+    return wrapped;
+}

package/src/core/shared/hashing.ts

@@ -1,67 +1,16 @@
 import { createHash } from "node:crypto";
 
-const CIRCULAR_STRUCTURE_MESSAGE =
-    "Cannot stably stringify a circular structure";
+import { canonicalStringify } from "./stable-stringify.js";
 
 function sha256Hex(value: string): string {
     return createHash("sha256").update(value, "utf8").digest("hex");
 }
 
-// `seen` holds the current traversal branch so true cycles are rejected while
-// repeated (acyclic) references are still serialized — matching JSON.stringify.
-function sortKeysDeep(value: unknown, seen: WeakSet<object>): unknown {
-    if (Array.isArray(value)) {
-        if (seen.has(value)) {
-            throw new TypeError(CIRCULAR_STRUCTURE_MESSAGE);
-        }
-        seen.add(value);
-        const mapped = value.map((item) => sortKeysDeep(item, seen));
-        seen.delete(value);
-        return mapped;
-    }
-
-    if (value instanceof Date) {
-        return value;
-    }
-
-    if (value && typeof value === "object") {
-        if (seen.has(value)) {
-            throw new TypeError(CIRCULAR_STRUCTURE_MESSAGE);
-        }
-        seen.add(value);
-        const record = value as Record<string, unknown>;
-        const ordered = Object.create(null) as Record<string, unknown>;
-
-        for (const key of Object.keys(record).sort()) {
-            ordered[key] = sortKeysDeep(record[key], seen);
-        }
-        seen.delete(value);
-
-        return ordered;
-    }
-
-    return value;
-}
-
-/**
- * Deterministic JSON string with object keys sorted recursively, so key order
- * does not affect the output.
- *
- * Follows `JSON.stringify` semantics for the values it serializes: `undefined`,
- * functions and symbols are dropped, non-finite numbers become `null`, `bigint`
- * throws, and `Map`/`Set` serialize as `{}`. Distinct payloads can therefore
- * collapse to the same string — for collision-resistant hashing use
- * `PolicyHashing.canonicalJson` (policies/utils), which rejects those values
- * up front.
- *
- * @throws {TypeError} On circular references (mirroring `JSON.stringify`).
- */
-function stableStringify(value: unknown): string {
-    return JSON.stringify(sortKeysDeep(value, new WeakSet<object>()));
-}
-
+// Strict by design: hashes the collision-resistant canonical form, so payloads
+// that differ only in values `JSON.stringify` would drop (undefined, NaN, …)
+// produce distinct digests instead of silently colliding.
 function payloadHash(value: unknown): string {
-    return sha256Hex(stableStringify(value));
+    return sha256Hex(canonicalStringify(value));
 }
 
-export { payloadHash, sha256Hex, stableStringify };
+export { payloadHash, sha256Hex };

package/src/core/shared/immutable.ts

@@ -26,6 +26,12 @@ function deepFreezeInternal<T>(value: T, seen: WeakSet<object>): T {
     // property — freezing it is a no-op against mutation. `makeImmutable`
     // already hands us a `structuredClone` copy, so the caller's original Date
     // is never aliased; deep-freezing of nested Dates is deliberately skipped.
+    //
+    // The same no-op caveat applies to `Map`/`Set`: `Object.freeze` locks the
+    // wrapper's own properties but not `.set`/`.delete`/`.clear`, which mutate
+    // internal slots. A frozen Map is still mutable through its methods. We do
+    // not neuter those methods here (no value object wraps a Map today); if one
+    // ever does, its immutability guarantee would be false — handle it there.
     if (typeof value !== "object" || value === null || value instanceof Date) {
         return value;
     }
@@ -48,7 +54,17 @@ function deepFreezeInternal<T>(value: T, seen: WeakSet<object>): T {
     const objectValue = value as Record<PropertyKey, object | PrimitiveValue>;
 
     for (const propertyKey of Reflect.ownKeys(objectValue)) {
-        deepFreezeInternal(objectValue[propertyKey], seen);
+        // Read through the descriptor rather than `objectValue[propertyKey]` so
+        // accessor properties are not invoked — a getter could have side effects
+        // or throw, and its computed result can't be frozen anyway. Only data
+        // properties hold a nested value worth recursing into.
+        const descriptor = Object.getOwnPropertyDescriptor(
+            objectValue,
+            propertyKey,
+        );
+        if (descriptor && "value" in descriptor) {
+            deepFreezeInternal(descriptor.value, seen);
+        }
     }
 
     return Object.freeze(value);
@@ -63,9 +79,11 @@ function makeImmutable<T>(value: T): DeepReadonly<T> {
     try {
         snapshot = structuredClone(value);
     } catch (error) {
-        // `structuredClone` throws `DataCloneError` for functions, symbols and
-        // class instances. Surface it as a domain invariant instead of leaking
-        // a host-specific runtime error to callers building value objects.
+        // `structuredClone` throws `DataCloneError` for functions and symbols.
+        // (Class instances do NOT throw — they are silently flattened to plain
+        // objects, prototype lost.) Surface the error as a domain invariant
+        // instead of leaking a host-specific runtime error to callers building
+        // value objects.
         throw new InvariantViolationException(
             `makeImmutable requires a structured-cloneable value: ${
                 error instanceof Error ? error.message : String(error)