@cullet/erp-core 1.0.0

package/src/core/errors/types.ts

@@ -0,0 +1,74 @@
+// Shared types for application errors.
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Severity levels
+// ─────────────────────────────────────────────────────────────────────────────
+
+type ErrorSeverity = "low" | "medium" | "high" | "critical";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// JSON-safe value types (for metadata serialization)
+// ─────────────────────────────────────────────────────────────────────────────
+
+type JsonSafePrimitive = string | number | boolean | null;
+
+type JsonSafeValue =
+  | JsonSafePrimitive
+  | JsonSafeValue[]
+  | { [key: string]: JsonSafeValue };
+
+type JsonSafeRecord = Record<string, JsonSafeValue>;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// AppError options (reusable across all error subclasses)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Options accepted by the AppError constructor.
+ * Subclasses can extend or pick from this type.
+ */
+type AppErrorOptions = {
+  /** Original error or exception that caused this error. */
+  cause?: unknown;
+
+  /** Arbitrary key-value metadata (will be sanitized to JSON-safe values). */
+  metadata?: Record<string, unknown>;
+
+  /** Error category/type for grouping (e.g., "authentication", "validation"). */
+  type?: string;
+
+  /** severity level for alerting/logging prioritization. */
+  severity?: ErrorSeverity;
+
+  /**
+   * Identifies a single execution "story" in the system. All operations
+   * related to the same logical flow must share the same correlationId.
+   */
+  correlationId?: string;
+
+  /**
+   * Identifies a specific technical request attempt (each retry may produce
+   * a new requestId), even when the correlationId stays the same.
+   */
+  requestId?: string;
+
+  /**
+   * Identifies a unique business intent (idempotency key); stays the same
+   * across technical retries and multiple requests that represent the same intent.
+   */
+  commandId?: string;
+
+  /** ISO timestamp of when the error was created (defaults to now). */
+  createdAtIso?: string;
+
+  /** Safe message that can be exposed to end users (no internal details). */
+  publicMessage?: string;
+};
+
+export type {
+  AppErrorOptions,
+  ErrorSeverity,
+  JsonSafePrimitive,
+  JsonSafeRecord,
+  JsonSafeValue,
+};

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

@@ -0,0 +1,22 @@
+import { AppError } from "./app-error";
+import { ErrorCodes } from "./error-codes";
+import type { AppErrorOptions } from "./types";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// UnexpectedError
+// ─────────────────────────────────────────────────────────────────────────────
+
+class UnexpectedError extends AppError {
+  constructor(
+    message = "Unexpected error",
+    cause?: unknown,
+    options?: Omit<AppErrorOptions, "cause">,
+  ) {
+    super(message, ErrorCodes.unexpected, {
+      cause,
+      ...options,
+    });
+  }
+}
+
+export { UnexpectedError };

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

@@ -0,0 +1,4 @@
+export {
+  assertJsonSafeMetadata,
+  NON_SERIALIZABLE_PLACEHOLDER,
+} from "./json-safe";

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

@@ -0,0 +1,93 @@
+// Utilities for ensuring metadata is JSON-serializable.
+
+import type { JsonSafeRecord, JsonSafeValue } from "../types";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Constants
+// ─────────────────────────────────────────────────────────────────────────────
+
+const NON_SERIALIZABLE_PLACEHOLDER = "[NonSerializable]";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Internal helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== "object") return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+function sanitizeValue(value: unknown): JsonSafeValue {
+  // Null passthrough
+  if (value === null) return null;
+
+  const type = typeof value;
+
+  // Primitives
+  if (type === "string" || type === "number" || type === "boolean") {
+    return value as JsonSafeValue;
+  }
+
+  // Non-serializable primitives
+  if (
+    type === "bigint" ||
+    type === "function" ||
+    type === "symbol" ||
+    value === undefined
+  ) {
+    return NON_SERIALIZABLE_PLACEHOLDER;
+  }
+
+  // Arrays (recursive)
+  if (Array.isArray(value)) {
+    return value.map(sanitizeValue);
+  }
+
+  // Date → placeholder (could also use .toISOString() if preferred)
+  if (value instanceof Date) {
+    return NON_SERIALIZABLE_PLACEHOLDER;
+  }
+
+  // Class instances and non-plain objects → placeholder
+  if (!isPlainObject(value)) {
+    return NON_SERIALIZABLE_PLACEHOLDER;
+  }
+
+  // Plain object (recursive)
+  const result: Record<string, JsonSafeValue> = {};
+  for (const [key, val] of Object.entries(value)) {
+    result[key] = sanitizeValue(val);
+  }
+  return result;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Public API
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Ensures metadata is JSON-serializable.
+ *
+ * **Allowed:** string, number, boolean, null, arrays, and plain objects.
+ *
+ * **Converted to placeholder:** Date, BigInt, class instances, functions,
+ * symbols, undefined.
+ *
+ * @throws {TypeError} If `input` is not a plain object at the root level.
+ */
+function assertJsonSafeMetadata(input: unknown): JsonSafeRecord {
+  if (input === undefined) {
+    return {};
+  }
+
+  if (!isPlainObject(input)) {
+    throw new TypeError(
+      "metadata must be a plain object (Record<string, unknown>).",
+    );
+  }
+
+  return sanitizeValue(input) as JsonSafeRecord;
+}
+
+export { assertJsonSafeMetadata, NON_SERIALIZABLE_PLACEHOLDER };

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

@@ -0,0 +1,34 @@
+import { ValidationCode } from "../exceptions/validation-code";
+import { ValidationField } from "../exceptions/validation-field";
+
+import { AppError } from "./app-error";
+import { ErrorCodes } from "./error-codes";
+import type { AppErrorOptions } from "./types";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// ValidationError
+// ─────────────────────────────────────────────────────────────────────────────
+
+class ValidationError extends AppError {
+  constructor(
+    field: ValidationField,
+    code: ValidationCode,
+    message: string,
+    options?: AppErrorOptions,
+  ) {
+    const baseMetadata = {
+      field: field.value,
+      validationCode: code.value,
+    };
+    const mergedMetadata = options?.metadata
+      ? { ...baseMetadata, ...options.metadata }
+      : baseMetadata;
+
+    super(message, ErrorCodes.validation, {
+      ...options,
+      metadata: mergedMetadata,
+    });
+  }
+}
+
+export { ValidationError };

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

@@ -0,0 +1,12 @@
+import { DomainException } from "./domain-exception";
+
+class BusinessRuleViolationException extends DomainException {
+  constructor(
+    public readonly rule: string,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+export { BusinessRuleViolationException };

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

@@ -0,0 +1,9 @@
+abstract class DomainException extends Error {
+  constructor(message: string) {
+    super(message);
+    Object.setPrototypeOf(this, new.target.prototype);
+    this.name = new.target.name;
+  }
+}
+
+export { DomainException };

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

@@ -0,0 +1,12 @@
+import { DomainException } from "./domain-exception";
+
+class EntityNotFoundException extends DomainException {
+  constructor(
+    public readonly entityName: string,
+    public readonly identifier: string,
+  ) {
+    super(`${entityName} with identifier ${identifier} was not found.`);
+  }
+}
+
+export { EntityNotFoundException };

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

@@ -0,0 +1,15 @@
+import { DomainException } from "./domain-exception";
+
+class InvalidStateTransitionException<
+  TState extends string = string,
+> extends DomainException {
+  constructor(
+    public readonly from: TState,
+    public readonly to: TState,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+export { InvalidStateTransitionException };

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

@@ -0,0 +1,9 @@
+import { DomainException } from "./domain-exception";
+
+class InvariantViolationException extends DomainException {
+  constructor(message: string) {
+    super(message);
+  }
+}
+
+export { InvariantViolationException };

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

@@ -0,0 +1,39 @@
+// Object-oriented representation of validation codes (similar to Kotlin inline class).
+// Provides common reusable codes while allowing custom codes via `of`.
+
+class ValidationCode {
+  public readonly value: string;
+
+  private constructor(value: string) {
+    this.value = value;
+  }
+
+  // Factory for custom codes
+  public static of(value: string): ValidationCode {
+    return new ValidationCode(value);
+  }
+
+  // Common, domain-friendly codes
+  public static readonly BLANK = new ValidationCode("blank");
+  public static readonly REQUIRED = new ValidationCode("required");
+  public static readonly INVALID_FORMAT = new ValidationCode("invalid_format");
+  public static readonly INVALID_CHARACTERS = new ValidationCode(
+    "invalid_characters",
+  );
+  public static readonly INVALID_LENGTH = new ValidationCode("invalid_length");
+  public static readonly TOO_SHORT = new ValidationCode("too_short");
+  public static readonly TOO_LONG = new ValidationCode("too_long");
+  public static readonly OUT_OF_RANGE = new ValidationCode("out_of_range");
+  public static readonly INVALID_CHECKSUM = new ValidationCode(
+    "invalid_checksum",
+  );
+  public static readonly INVALID_CHECKING_DIGIT = new ValidationCode(
+    "invalid_checking_digit",
+  );
+  public static readonly ALREADY_EXISTS = new ValidationCode("already_exists");
+  public static readonly NOT_FOUND = new ValidationCode("not_found");
+  public static readonly NOT_ALLOWED = new ValidationCode("not_allowed");
+  public static readonly UNEXPECTED = new ValidationCode("unexpected");
+}
+
+export { ValidationCode };

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

@@ -0,0 +1,39 @@
+import { DomainException } from "./domain-exception";
+import { ValidationCode } from "./validation-code";
+import { ValidationField } from "./validation-field";
+
+export interface ValidationViolation {
+  readonly field: ValidationField;
+  readonly code: ValidationCode;
+  readonly message: string;
+}
+
+class ValidationException extends DomainException {
+  constructor(
+    public readonly field: ValidationField,
+    public readonly code: ValidationCode,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+// Carries multiple validation violations from a single operation (e.g. bulk validation).
+// Use when you need to report all field errors at once rather than failing on the first.
+class MultipleValidationException extends DomainException {
+  constructor(public readonly violations: readonly ValidationViolation[]) {
+    super(violations.map((v) => v.message).join("; "));
+  }
+}
+
+class InvalidValueException extends ValidationException {
+  constructor(field: ValidationField, code: ValidationCode, message: string) {
+    super(field, code, message);
+  }
+}
+
+export {
+  InvalidValueException,
+  MultipleValidationException,
+  ValidationException,
+};

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

@@ -0,0 +1,32 @@
+// Object-oriented representation of validation fields.
+// Indicates WHERE a validation error occurred.
+// This is a minimal base class — field catalogs are defined per domain/module.
+
+class ValidationField {
+  public readonly value: string;
+
+  private constructor(value: string) {
+    this.value = value;
+  }
+
+  // Factory for custom or domain-specific fields
+  public static of(value: string): ValidationField {
+    return new ValidationField(value);
+  }
+
+  // Creates a nested field path: parent.nested('child') -> 'parent.child'
+  public nested(child: string | ValidationField): ValidationField {
+    const childValue = child instanceof ValidationField ? child.value : child;
+    return new ValidationField(`${this.value}.${childValue}`);
+  }
+
+  public toString(): string {
+    return this.value;
+  }
+
+  public equals(other: ValidationField): boolean {
+    return this.value === other.value;
+  }
+}
+
+export { ValidationField };

package/src/core/index.ts

@@ -0,0 +1,15 @@
+export * from "./errors";
+export * from "./exceptions/validation-field";
+export type {
+  LogPayload,
+  LoggerPort,
+  MetricLabels,
+  MetricsPort,
+  TraceAttributeValue,
+  TraceSpan,
+  TracerPort,
+} from "./application";
+export { mapPolicyEvaluationError } from "./application/policy-error-mapper";
+export { Entity, type EntityState } from "./domain/entity";
+export { ValueObject, type DeepReadonly } from "./domain/value-object";
+export * from "./policies";

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

@@ -0,0 +1,68 @@
+import type { AsOfSource } from "../catalog";
+import type { ContextSeed } from "../context";
+import { Result } from "../../result/result";
+import { isValidDate } from "../../shared/temporal-guards";
+
+const DEFAULT_MAX_AS_OF_FUTURE_YEARS = 10;
+
+export interface DeriveAsOfOptions {
+  readonly maxFutureYears?: number;
+}
+
+export class PolicyAsOfResolver {
+  private static resolveMaxFutureYears(
+    options: DeriveAsOfOptions,
+  ): Result<number, string> {
+    const maxFutureYears =
+      options.maxFutureYears ?? DEFAULT_MAX_AS_OF_FUTURE_YEARS;
+
+    if (!Number.isInteger(maxFutureYears) || maxFutureYears < 0) {
+      return Result.err(
+        `deriveAsOf maxFutureYears must be a non-negative integer. Received: ${maxFutureYears}`,
+      );
+    }
+
+    return Result.ok(maxFutureYears);
+  }
+
+  static derive(
+    source: AsOfSource,
+    seed: ContextSeed,
+    now: Date,
+    options: DeriveAsOfOptions = {},
+  ): Result<Date, string> {
+    const maxFutureYearsResult =
+      PolicyAsOfResolver.resolveMaxFutureYears(options);
+    if (maxFutureYearsResult.isErr()) {
+      return Result.err(maxFutureYearsResult.errorOrNull()!);
+    }
+    const maxFutureYears = maxFutureYearsResult.getOrNull()!;
+
+    switch (source) {
+      case "NOW":
+        return Result.ok(now);
+
+      case "CALLER_PROVIDED": {
+        const asOf = seed.fields["asOf"];
+        if (!isValidDate(asOf)) {
+          return Result.err(
+            'asOfSource "CALLER_PROVIDED" requires seed.fields.asOf to be a Date',
+          );
+        }
+
+        const maxFuture = new Date(now);
+        maxFuture.setFullYear(maxFuture.getFullYear() + maxFutureYears);
+        if (asOf > maxFuture) {
+          return Result.err(
+            `asOf date is more than ${maxFutureYears} years in the future (received ${asOf.toISOString()})`,
+          );
+        }
+
+        return Result.ok(asOf);
+      }
+
+      default:
+        return Result.err(`Unknown asOfSource: "${source}"`);
+    }
+  }
+}

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

@@ -0,0 +1,2 @@
+export { PolicyAsOfResolver } from "./asof";
+export type { DeriveAsOfOptions } from "./asof";

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

@@ -0,0 +1,12 @@
+// ─── Enums / Literal unions ─────────────────────────────────────────────────
+
+export type PolicyKind = "GATE" | "COMPUTE";
+
+export type PolicyOwner = "PLATFORM_OWNER" | "TENANT_ADMIN" | "SCHOOL_ADMIN";
+
+export type PolicyScopeLevel = "GLOBAL" | "TENANT" | "SCHOOL";
+
+/**
+ * Defines where the "as of" date comes from for a given policy.
+ */
+export type AsOfSource = "NOW" | "CALLER_PROVIDED";

package/src/core/policies/catalog/catalog.instance.ts

@@ -0,0 +1,21 @@
+import type { PolicyPackage } from "../package/policy-package";
+
+import { PolicyCatalog } from "./policy-catalog";
+import { PolicyCatalogEntry } from "./policy-catalog-entry";
+
+// ─── Factory ────────────────────────────────────────────────────────────────
+
+/**
+ * Aggregates catalog entries contributed by each module package into a single
+ * PolicyCatalog. The core knows nothing about concrete modules — callers
+ * are responsible for passing all relevant packages at composition time.
+ */
+export class PolicyCatalogFactory {
+  static build(packages: readonly PolicyPackage[]): PolicyCatalog {
+    const entries = packages.flatMap((policyPackage) =>
+      Array.from(policyPackage.catalogEntries).map(PolicyCatalogEntry.from),
+    );
+
+    return new PolicyCatalog(entries);
+  }
+}

package/src/core/policies/catalog/index.ts

@@ -0,0 +1,11 @@
+export type {
+  AsOfSource,
+  PolicyKind,
+  PolicyOwner,
+  PolicyScopeLevel,
+} from "./catalog-types";
+export type { PolicyCatalogEntryProps } from "./policy-catalog-entry";
+export { PolicyCatalogEntry } from "./policy-catalog-entry";
+export { PolicyCatalog } from "./policy-catalog";
+export { PolicyCatalogFactory } from "./catalog.instance";
+export { PolicyKey } from "./policy-key";