@cullet/erp-core 1.4.0 → 2.0.0

package/src/core/domain/temporal/valid-time.ts

@@ -1,10 +1,22 @@
-import { InvariantViolationException } from "../../exceptions/invariant-violation-exception.js";
 import { makeImmutable } from "../../shared/immutable.js";
-import { assertValidDate } from "../../shared/temporal-guards.js";
+
+import { assertHalfOpenInterval } from "./half-open-interval.js";
 
 /**
  * Represents business time (Valid Time).
  * Defines when a piece of information is considered true or in effect in the real world.
+ *
+ * The window is half-open — `from` inclusive, `to` exclusive — and strictly
+ * non-empty: `to` must be later than `from`, so a zero-duration range `[t, t)`
+ * is deliberately not representable. Model an instantaneous event as an open
+ * range closed by the next fact, not as an empty window.
+ *
+ * One caveat mirrors {@link ValueObject}: `createValidTime` clones the input
+ * dates (no aliasing) but the inner `Date`s are NOT frozen — `Object.freeze`
+ * cannot block `setTime`/`setFullYear`, so a caller can still mutate `from`
+ * in place and corrupt the range after creation. `readonly` only prevents
+ * reassignment. Treat the dates as read-only, or keep instants as ISO/epoch in
+ * your own state when that guarantee matters.
  */
 interface ValidTime {
     /** Start of the validity window (inclusive). */
@@ -19,19 +31,12 @@ function assertValidTime(
     validTime: ValidTime,
     fieldName: string = "validTime",
 ): void {
-    assertValidDate(`${fieldName}.from`, validTime.from);
-
-    if (validTime.to === undefined) {
-        return;
-    }
-
-    assertValidDate(`${fieldName}.to`, validTime.to);
-
-    if (validTime.to.getTime() <= validTime.from.getTime()) {
-        throw new InvariantViolationException(
-            `${fieldName}.to must be later than ${fieldName}.from`,
-        );
-    }
+    assertHalfOpenInterval(
+        `${fieldName}.from`,
+        validTime.from,
+        `${fieldName}.to`,
+        validTime.to,
+    );
 }
 
 function createValidTime(input: CreateValidTimeInput): ValidTime {

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.
  *
@@ -45,7 +38,7 @@ abstract class UuidIdentifier<
      * two identifiers with different brands are not interchangeable at the type
      * level despite sharing the same `string` value.
      */
-    protected declare readonly __brand: TBrand;
+    declare protected readonly __brand: TBrand;
 
     protected constructor(value: string) {
         super(value);
@@ -61,8 +54,10 @@ abstract class UuidIdentifier<
     }
 
     /**
-     * Whether `candidate` is a canonical UUID (versions 1–5). The single source
-     * of truth for the format; concrete identifiers call this from `create`.
+     * Whether `candidate` is a canonical UUID (versions 1–8, including the
+     * time-ordered v7; nil and max UUIDs are rejected as sentinels). The single
+     * source of truth for the format — see `shared/uuid.ts`; concrete
+     * identifiers call this from `create`.
      */
     public static isValid(candidate: string): boolean {
         return UUID_PATTERN.test(candidate);

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}.
  */
@@ -40,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>();
@@ -61,7 +75,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 +107,25 @@ 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.
+     *
+     * 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) =>
-                JSON.stringify(a.value) === JSON.stringify(b.value),
+                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,