@cullet/erp-core 1.5.0 → 2.0.0

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

@@ -47,6 +47,13 @@ abstract class ValueObject<T, P> {
      * default — when nothing is registered, {@link equals} falls back to a
      * structural comparison of the wrapped `value`. Hosts register a plugin
      * (e.g. `lodash.isEqual`) once at startup to customise equality globally.
+     *
+     * "Globally" is literal: this static registry is process-wide and shared
+     * by **every** `ValueObject` subclass, including the value objects the kit
+     * itself ships (RBAC's `Permission`, `Scope`, …). A registered plugin
+     * therefore redefines equality for those too — it must honour generic
+     * value-object semantics, not the quirks of one host type. For a
+     * type-specific comparison, override `equals` on that subclass instead.
      */
     public static readonly plugins =
         new PluginManager<ValueObjectPluginContract>();
@@ -104,10 +111,20 @@ abstract class ValueObject<T, P> {
      * 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.
+     *
+     * The fallback also requires both sides to be the same concrete class, so
+     * an `OrderId` never equals a `CustomerId` that wraps the same string —
+     * `other: this` only guards at compile time, and a cast would otherwise
+     * slip through. And because the fallback serializes via `stableStringify`,
+     * it inherits `JSON.stringify` semantics: `undefined` properties are
+     * dropped (`{a: 1, b: undefined}` equals `{a: 1}`) and `Map`/`Set` collapse
+     * to `{}` — see the caveats in `shared/stable-stringify.ts`. Override
+     * `equals` when the wrapped value relies on such shapes.
      */
     public equals(other: this): boolean {
         return ValueObject.plugins.invoke("equals", [this, other], {
             fallback: (a, b) =>
+                a.constructor === b.constructor &&
                 stableStringify(a.value) === stableStringify(b.value),
         });
     }

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

@@ -1,6 +1,7 @@
 import { AppError } from "./app-error.js";
 import { ErrorCodes } from "./error-codes.js";
 import type { AppErrorOptions, ErrorSeverity } from "./types.js";
+import { compactMetadata, pickAppErrorOptions } from "./utils/index.js";
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Types
@@ -85,7 +86,7 @@ class AuthenticationError extends AppError {
             code: ErrorCodes.authentication.missingToken,
             reason: "missing_token",
             metadata: compactMetadata(options),
-            ...extractAppErrorOptions(options),
+            ...pickAppErrorOptions(options),
         });
     }
 
@@ -103,7 +104,7 @@ class AuthenticationError extends AppError {
                 correlationId: options?.correlationId,
                 requestId: options?.requestId,
             }),
-            ...extractAppErrorOptions(options),
+            ...pickAppErrorOptions(options),
         });
     }
 
@@ -115,7 +116,7 @@ class AuthenticationError extends AppError {
             code: ErrorCodes.authentication.expiredToken,
             reason: "expired_token",
             metadata: compactMetadata(options),
-            ...extractAppErrorOptions(options),
+            ...pickAppErrorOptions(options),
         });
     }
 
@@ -135,37 +136,10 @@ class AuthenticationError extends AppError {
             code: ErrorCodes.authentication.invalidCredentials,
             reason: "invalid_credentials",
             metadata: compactMetadata(options),
-            ...extractAppErrorOptions(options),
+            ...pickAppErrorOptions(options),
         });
     }
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
-// Helpers
-// ─────────────────────────────────────────────────────────────────────────────
-
-function extractAppErrorOptions(options?: Partial<AppErrorOptions>) {
-    return {
-        cause: options?.cause,
-        type: options?.type,
-        severity: options?.severity,
-        correlationId: options?.correlationId,
-        requestId: options?.requestId,
-        commandId: options?.commandId,
-        createdAtIso: options?.createdAtIso,
-        publicMessage: options?.publicMessage,
-    };
-}
-
-function compactMetadata<T extends Record<string, unknown>>(
-    input?: T,
-): T | undefined {
-    if (!input) return undefined;
-
-    return Object.fromEntries(
-        Object.entries(input).filter(([, value]) => value !== undefined),
-    ) as T;
-}
-
 export { AuthenticationError };
 export type { AuthenticationErrorMetadata, AuthenticationErrorReason };

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

@@ -1,6 +1,7 @@
 import { AppError } from "./app-error.js";
 import { ErrorCodes } from "./error-codes.js";
 import type { AppErrorOptions, ErrorSeverity } from "./types.js";
+import { pickAppErrorOptions } from "./utils/index.js";
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Types
@@ -30,8 +31,12 @@ type AuthorizationErrorMetadata = {
     /** Resource identification (without leaking the full payload) */
     resource?: { type: string; id?: string };
 
-    /** Optional: actor (do not include sensitive data) */
-    actor?: { userId: string; role?: string };
+    /**
+     * Optional: the acting principal (do not include sensitive data). `actorId`
+     * is the raw `RequestedBy` value — a user UUID *or* a `"system:<job>"`
+     * identity — so it must not be assumed to be a human user.
+     */
+    actor?: { actorId: string; role?: string };
 
     /** Optional: expected requirement */
     required?: AuthorizationRequirement;
@@ -125,7 +130,7 @@ class AuthorizationError extends AppError {
             code: ErrorCodes.authorization.forbidden,
             reason: "forbidden",
             metadata: { reason: "forbidden", ...extractMetadataOnly(input) },
-            ...extractAppErrorOptions(input),
+            ...pickAppErrorOptions(input),
         });
     }
 
@@ -154,7 +159,7 @@ class AuthorizationError extends AppError {
                 ...extractMetadataOnly(input),
                 decision: "deny",
             },
-            ...extractAppErrorOptions(input),
+            ...pickAppErrorOptions(input),
         });
     }
 
@@ -180,7 +185,7 @@ class AuthorizationError extends AppError {
                 reason: "missing_role",
                 ...extractMetadataOnly(input),
             },
-            ...extractAppErrorOptions(input),
+            ...pickAppErrorOptions(input),
         });
     }
 
@@ -204,7 +209,7 @@ class AuthorizationError extends AppError {
                 reason: "missing_capability",
                 ...extractMetadataOnly(input),
             },
-            ...extractAppErrorOptions(input),
+            ...pickAppErrorOptions(input),
         });
     }
 
@@ -226,7 +231,7 @@ class AuthorizationError extends AppError {
             code: ErrorCodes.authorization.outOfScope,
             reason: "out_of_scope",
             metadata: { reason: "out_of_scope", ...extractMetadataOnly(input) },
-            ...extractAppErrorOptions(input),
+            ...pickAppErrorOptions(input),
         });
     }
 }
@@ -235,19 +240,6 @@ class AuthorizationError extends AppError {
 // Helpers
 // ─────────────────────────────────────────────────────────────────────────────
 
-function extractAppErrorOptions(options?: Partial<AppErrorOptions>) {
-    return {
-        cause: options?.cause,
-        type: options?.type,
-        severity: options?.severity,
-        correlationId: options?.correlationId,
-        requestId: options?.requestId,
-        commandId: options?.commandId,
-        createdAtIso: options?.createdAtIso,
-        publicMessage: options?.publicMessage,
-    };
-}
-
 function extractMetadataOnly(
     input: AuthorizationErrorFactoryOptions,
 ): Omit<AuthorizationErrorMetadata, "reason"> {

package/src/core/errors/business-rule-violation-error.ts

@@ -14,14 +14,17 @@ class BusinessRuleViolationError extends AppError {
         options?: AppErrorOptions,
     ) {
         const baseMetadata = detail ? { rule, detail } : { rule };
+        // Reserved keys (`rule`/`detail`) spread last so caller metadata cannot
+        // clobber them.
         const mergedMetadata = options?.metadata
-            ? { ...baseMetadata, ...options.metadata }
+            ? { ...options.metadata, ...baseMetadata }
             : baseMetadata;
 
         super(message, ErrorCodes.businessRuleViolation, {
             ...options,
             metadata: mergedMetadata,
         });
+        Object.freeze(this);
     }
 }
 

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

@@ -1,4 +1,5 @@
-import { payloadHash, sha256Hex, stableStringify } from "../shared/hashing.js";
+import { payloadHash, sha256Hex } from "../shared/hashing.js";
+import { stableStringify } from "../shared/stable-stringify.js";
 
 import { AppError } from "./app-error.js";
 import { ErrorCodes } from "./error-codes.js";
@@ -359,7 +360,9 @@ function resolveKeyIdentity(
         (key ? (key.length <= 8 ? key : key.slice(0, 8)) : undefined);
 
     return {
-        keyHash: keyHash,
+        // Derive the hash from the raw key when the caller didn't supply one —
+        // cheap traceability without leaking the key itself.
+        keyHash: keyHash ?? (key ? sha256Hex(key) : undefined),
         keyPreview: preview,
     };
 }

package/src/core/errors/index.ts

@@ -74,6 +74,8 @@ export type {
     SerializationFailureCategory,
 } from "./serialization-error.js";
 export {
+    // `DeserializationError` is a readability alias for the inbound direction
+    // (deserialization == SerializationInError); both names are public API.
     SerializationInError as DeserializationError,
     safePreview,
     SerializationCodes,
@@ -83,6 +85,8 @@ export {
     SerializationOutError,
 } from "./serialization-error.js";
 export type {
+    // `ExpiredError*` aliases are kept for callers that reach for the
+    // expiry-specific name; they are the same shapes as the generic Temporal*.
     TemporalErrorMetadata as ExpiredErrorMetadata,
     TemporalPrecision as ExpiredErrorPrecision,
     TemporalErrorMetadata,

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

@@ -1,6 +1,7 @@
 import type { AppErrorOptions, ErrorSeverity } from "./types.js";
 import { AppError } from "./app-error.js";
 import { ErrorCodes } from "./error-codes.js";
+import { compactMetadata, pickAppErrorOptions } from "./utils/index.js";
 
 type IntegrationErrorReason =
     | "timeout"
@@ -78,7 +79,7 @@ class IntegrationError extends AppError {
             code: ErrorCodes.integration.timeout,
             reason: "timeout",
             metadata: buildMetadata({ reason: "timeout", ...options }),
-            ...pickAppErrorFields(options),
+            ...pickAppErrorOptions(options),
         });
     }
 
@@ -94,7 +95,7 @@ class IntegrationError extends AppError {
             code: ErrorCodes.integration.unreachable,
             reason: "unreachable",
             metadata: buildMetadata({ reason: "unreachable", ...options }),
-            ...pickAppErrorFields(options),
+            ...pickAppErrorOptions(options),
         });
     }
 
@@ -111,7 +112,7 @@ class IntegrationError extends AppError {
             code: ErrorCodes.integration.badResponse,
             reason: "bad_response",
             metadata: buildMetadata({ reason: "bad_response", ...options }),
-            ...pickAppErrorFields(options),
+            ...pickAppErrorOptions(options),
         });
     }
 }
@@ -157,26 +158,5 @@ function buildMetadata(
     }) as IntegrationErrorMetadata;
 }
 
-function pickAppErrorFields(
-    options: IntegrationErrorBaseOptions,
-): IntegrationErrorAppOptions {
-    return {
-        cause: options.cause,
-        type: options.type,
-        severity: options.severity,
-        correlationId: options.correlationId,
-        requestId: options.requestId,
-        commandId: options.commandId,
-        createdAtIso: options.createdAtIso,
-        publicMessage: options.publicMessage,
-    };
-}
-
-function compactMetadata<T extends Record<string, unknown>>(input: T): T {
-    return Object.fromEntries(
-        Object.entries(input).filter(([, value]) => value !== undefined),
-    ) as T;
-}
-
 export { IntegrationError };
 export type { IntegrationErrorReason, IntegrationErrorMetadata };

package/src/core/errors/legacy-incompatible-error.ts

@@ -20,6 +20,7 @@ class LegacyIncompatibleError extends AppError {
             ...options,
             metadata: mergedMetadata,
         });
+        Object.freeze(this);
     }
 }
 

package/src/core/errors/not-found-error.ts

@@ -27,14 +27,17 @@ class NotFoundError extends AppError {
         options?: AppErrorOptions,
     ) {
         const baseMetadata = criteria ? { resource, criteria } : { resource };
+        // Reserved keys (`resource`/`criteria`) spread last so caller metadata
+        // can add to but never clobber them — as the docs promise.
         const mergedMetadata = options?.metadata
-            ? { ...baseMetadata, ...options.metadata }
+            ? { ...options.metadata, ...baseMetadata }
             : baseMetadata;
 
         super(`${resource} not found`, ErrorCodes.notFound, {
             ...options,
             metadata: mergedMetadata,
         });
+        Object.freeze(this);
     }
 }
 

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

@@ -1,6 +1,7 @@
 import { AppError } from "./app-error.js";
 import { ErrorCodes } from "./error-codes.js";
 import type { AppErrorOptions } from "./types.js";
+import { pickAppErrorOptions, stripAppErrorOptions } from "./utils/index.js";
 
 type TemporalKind = "expired" | "not_yet_valid";
 
@@ -66,19 +67,12 @@ class ExpiredError extends TemporalError {
             code: ErrorCodes.temporal.expired,
             kind: "expired",
             metadata: {
-                ...input,
+                ...stripAppErrorOptions(input),
                 hint:
                     input.hint ??
                     "The window has expired. Request a new link or try again within the valid period.",
             },
-            cause: input.cause,
-            type: input.type,
-            severity: input.severity,
-            correlationId: input.correlationId,
-            requestId: input.requestId,
-            commandId: input.commandId,
-            createdAtIso: input.createdAtIso,
-            publicMessage: input.publicMessage,
+            ...pickAppErrorOptions(input),
         });
     }
 }
@@ -94,23 +88,31 @@ class NotYetValidError extends TemporalError {
             code: ErrorCodes.temporal.notYetValid,
             kind: "not_yet_valid",
             metadata: {
-                ...input,
+                ...stripAppErrorOptions(input),
                 hint:
                     input.hint ??
                     "Not yet within the valid period. Try again later.",
             },
-            cause: input.cause,
-            type: input.type,
-            severity: input.severity,
-            correlationId: input.correlationId,
-            requestId: input.requestId,
-            commandId: input.commandId,
-            createdAtIso: input.createdAtIso,
-            publicMessage: input.publicMessage,
+            ...pickAppErrorOptions(input),
         });
     }
 }
 
+/**
+ * Evaluates whether `evaluatedAtIso` falls inside the [`validFromIso`,
+ * `validUntilIso`] window.
+ *
+ * Fails **closed**: a boundary that is present but unparseable is treated as if
+ * the window were closed on that side (a bad `validUntilIso` → expired, a bad
+ * `validFromIso` → not-yet-valid), never silently ignored — these checks guard
+ * access (invites, links, tokens), so a typo in an expiry must not disable
+ * expiry. A `null`/absent boundary means "no bound on that side", which is
+ * distinct from a malformed one. Returns `null` only when `evaluatedAtIso`
+ * itself is unparseable (nothing can be decided).
+ *
+ * For an inverted window (`validFrom` > `validUntil`) `expired` wins, since the
+ * upper-bound check short-circuits.
+ */
 function evaluateTemporalWindow(input: {
     validFromIso?: string | null;
     validUntilIso?: string | null;
@@ -123,14 +125,14 @@ function evaluateTemporalWindow(input: {
 
     if (input.validFromIso) {
         const fromMs = Date.parse(input.validFromIso);
-        if (!Number.isNaN(fromMs) && evaluatedMs < fromMs) {
+        if (Number.isNaN(fromMs) || evaluatedMs < fromMs) {
             notYetValid = true;
         }
     }
 
     if (input.validUntilIso) {
         const untilMs = Date.parse(input.validUntilIso);
-        if (!Number.isNaN(untilMs) && evaluatedMs > untilMs) {
+        if (Number.isNaN(untilMs) || evaluatedMs > untilMs) {
             return { expired: true, notYetValid: false };
         }
     }

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

@@ -12,10 +12,14 @@ class UnexpectedError extends AppError {
         cause?: unknown,
         options?: Omit<AppErrorOptions, "cause">,
     ) {
+        // The error you most want alerted on defaults to "critical" — a caller
+        // can still lower it via options.severity.
         super(message, ErrorCodes.unexpected, {
-            cause,
+            severity: "critical",
             ...options,
+            cause,
         });
+        Object.freeze(this);
     }
 }
 

package/src/core/errors/utils/factory-helpers.ts

@@ -0,0 +1,70 @@
+// Shared helpers for the error factories: separating the AppError envelope
+// options from the free-form metadata, and dropping undefined-valued keys.
+// Previously each of authentication/authorization/integration carried its own
+// near-identical copy of these.
+
+import type { AppErrorOptions } from "../types.js";
+
+/** The envelope fields AppError understands; everything else is metadata. */
+const APP_ERROR_OPTION_KEYS = [
+    "cause",
+    "type",
+    "severity",
+    "correlationId",
+    "requestId",
+    "commandId",
+    "createdAtIso",
+    "publicMessage",
+] as const;
+
+type AppErrorEnvelope = Pick<
+    AppErrorOptions,
+    (typeof APP_ERROR_OPTION_KEYS)[number]
+>;
+
+/**
+ * Picks the AppError envelope fields out of a flat factory input, so they can
+ * be forwarded to the constructor as options instead of leaking into metadata.
+ */
+function pickAppErrorOptions(
+    input?: Partial<AppErrorOptions>,
+): AppErrorEnvelope {
+    return {
+        cause: input?.cause,
+        type: input?.type,
+        severity: input?.severity,
+        correlationId: input?.correlationId,
+        requestId: input?.requestId,
+        commandId: input?.commandId,
+        createdAtIso: input?.createdAtIso,
+        publicMessage: input?.publicMessage,
+    };
+}
+
+/**
+ * The complement of {@link pickAppErrorOptions}: everything that is *not* an
+ * AppError envelope field, i.e. the caller-supplied metadata. Keeps the cause
+ * and the public message out of the internal data block.
+ */
+function stripAppErrorOptions<T extends Record<string, unknown>>(
+    input: T,
+): Omit<T, (typeof APP_ERROR_OPTION_KEYS)[number]> {
+    const result = { ...input };
+    for (const key of APP_ERROR_OPTION_KEYS) {
+        delete result[key];
+    }
+    return result;
+}
+
+/** Drops keys whose value is `undefined` (mirrors how JSON.stringify treats them). */
+function compactMetadata<T extends Record<string, unknown>>(
+    input?: T,
+): T | undefined {
+    if (!input) return undefined;
+
+    return Object.fromEntries(
+        Object.entries(input).filter(([, value]) => value !== undefined),
+    ) as T;
+}
+
+export { compactMetadata, pickAppErrorOptions, stripAppErrorOptions };

package/src/core/errors/utils/index.ts

@@ -1,3 +1,8 @@
+export {
+    compactMetadata,
+    pickAppErrorOptions,
+    stripAppErrorOptions,
+} from "./factory-helpers.js";
 export {
     assertJsonSafeMetadata,
     CIRCULAR_REFERENCE_PLACEHOLDER,

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

@@ -75,7 +75,21 @@ function sanitizeValue(value: unknown, seen: WeakSet<object>): JsonSafeValue {
     const result: Record<string, JsonSafeValue> = {};
     for (const [key, val] of Object.entries(value)) {
         if (val === undefined) continue;
-        result[key] = sanitizeValue(val, seen);
+        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;

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");