@cullet/erp-core 1.0.0

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

@@ -0,0 +1,2 @@
+export type { CacheStrategy, Page } from "./query";
+export { Query } from "./query";

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

@@ -0,0 +1,53 @@
+import { UseCase } from "../use-case";
+import { version } from "../../versioning/version";
+import type { AppError } from "../../errors";
+import type { Result } from "../../result/result";
+
+/**
+ * Paginated result of a list query.
+ * Use as `Output` when the query returns a collection with pagination metadata.
+ */
+interface Page<T> {
+  readonly items: readonly T[];
+  readonly total: number;
+  readonly page: number;
+  readonly pageSize: number;
+}
+
+/**
+ * Cache strategy declared by the query type.
+ * Infrastructure reads this value to decide whether and how to cache the result.
+ */
+type CacheStrategy =
+  | { readonly kind: "NO_CACHE" }
+  | { readonly kind: "TIME_TO_LIVE"; readonly ttlMs: number }
+  | { readonly kind: "STALE_WHILE_REVALIDATE"; readonly ttlMs: number };
+
+type QueryOutput = object | string | number | boolean | bigint | symbol | null;
+
+/**
+ * Base for use cases that **only read state**, with no side effects, following CQS.
+ *
+ * - `Data extends QueryOutput` prevents a query from declaring a `void` or
+ *   `undefined` success payload, while still allowing primitive projections
+ *   and `null` when that makes sense for the read. Failures stay explicit in
+ *   `Result<T, E>`.
+ * - Override `cacheStrategy()` to declare how infrastructure should cache the
+ *   result. By default, no cache is applied.
+ *
+ * A Query must never mutate persisted data — its execution must be idempotent
+ * and safe to call multiple times with the same input.
+ */
+@version("1.0")
+abstract class Query<
+  Input = void,
+  Data extends QueryOutput = never,
+  Failure = AppError,
+> extends UseCase<Input, Result<Data, Failure>> {
+  protected cacheStrategy(): CacheStrategy {
+    return { kind: "NO_CACHE" };
+  }
+}
+
+export type { CacheStrategy, Page, QueryOutput };
+export { Query };

package/src/core/application/temporal/index.ts

@@ -0,0 +1,11 @@
+export {
+  assertTemporalContext,
+  createTemporalContext,
+  type CreateTemporalContextInput,
+  type TemporalContext,
+} from "./temporal-context";
+export {
+  type TemporalUseCaseInput,
+  type TemporalizedContextSeed,
+  TemporalUseCase,
+} from "./temporal-use-case";

package/src/core/application/temporal/temporal-context.ts

@@ -0,0 +1,41 @@
+import { makeImmutable } from "../../shared/immutable";
+import { assertValidDate } from "../../shared/temporal-guards";
+
+interface TemporalContext {
+  readonly asOf: Date;
+  readonly requestedAt: Date;
+}
+
+interface CreateTemporalContextInput {
+  readonly asOf?: Date;
+  readonly requestedAt?: Date;
+}
+
+function assertTemporalContext(
+  temporalContext: TemporalContext,
+  fieldName: string = "temporalContext",
+): void {
+  assertValidDate(`${fieldName}.asOf`, temporalContext.asOf);
+  assertValidDate(`${fieldName}.requestedAt`, temporalContext.requestedAt);
+}
+
+function createTemporalContext(
+  input: CreateTemporalContextInput = {},
+): TemporalContext {
+  const requestedAt = input.requestedAt ?? new Date();
+  const asOf = input.asOf ?? requestedAt;
+
+  assertTemporalContext({ asOf, requestedAt });
+
+  return makeImmutable({
+    asOf,
+    requestedAt,
+  });
+}
+
+export {
+  assertTemporalContext,
+  createTemporalContext,
+  type CreateTemporalContextInput,
+  type TemporalContext,
+};

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

@@ -0,0 +1,41 @@
+import { UseCase } from "../use-case";
+import type { ContextSeed } from "../../policies";
+import type { Result } from "../../result/result";
+
+import {
+  createTemporalContext,
+  type TemporalContext,
+} from "./temporal-context";
+
+interface TemporalUseCaseInput {
+  readonly temporalContext?: TemporalContext;
+}
+
+type TemporalizedContextSeed<TSeed extends ContextSeed> = TSeed;
+
+abstract class TemporalUseCase<
+  Input extends object,
+  Output extends Result<unknown, unknown>,
+> extends UseCase<Input & TemporalUseCaseInput, Output> {
+  protected resolveTemporalContext(
+    input: Input & TemporalUseCaseInput,
+  ): TemporalContext {
+    return createTemporalContext(input.temporalContext);
+  }
+
+  protected buildPolicySeed<TSeed extends ContextSeed>(
+    seed: TSeed,
+    temporalContext: TemporalContext,
+  ): TemporalizedContextSeed<TSeed> {
+    return Object.freeze({
+      ...seed,
+      fields: {
+        ...seed.fields,
+        now: new Date(temporalContext.requestedAt.getTime()),
+      },
+    }) as TSeed;
+  }
+}
+
+export type { TemporalizedContextSeed, TemporalUseCaseInput };
+export { TemporalUseCase };

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

@@ -0,0 +1,24 @@
+import { type ContractVersion, version } from "../versioning/version";
+import type { Result } from "../result/result";
+
+type MaybePromise<T> = T | Promise<T>;
+
+@version("1.0")
+abstract class UseCase<
+  Input = void,
+  Output extends Result<unknown, unknown> = Result<void, never>,
+> {
+  public static readonly CONTRACT_VERSION: ContractVersion;
+
+  public get contractVersion(): ContractVersion {
+    return UseCase.CONTRACT_VERSION;
+  }
+
+  public async run(input: Input): Promise<Output> {
+    return await this.execute(input);
+  }
+
+  protected abstract execute(input: Input): MaybePromise<Output>;
+}
+
+export { type MaybePromise, UseCase };

package/src/core/config/core-config.instance.ts

@@ -0,0 +1,14 @@
+import { CoreConfig } from "./core-config";
+import { SilentPolicyReporter } from "./silent-policy-reporter";
+
+/**
+ * Shared instance for the application composition root.
+ * Use `new CoreConfig()` for isolated runtimes, tests, or multi-tenant hosts.
+ *
+ * The default reporter is silent so the core has no runtime logging dependency.
+ * Hosts can swap in their own `PolicyReporter` via
+ * `coreConfig.configure({ observability: { reporter } })`.
+ */
+export const coreConfig = new CoreConfig({
+  observability: { reporter: new SilentPolicyReporter() },
+});

package/src/core/config/core-config.ts

@@ -0,0 +1,87 @@
+import type {
+  ConditionEvaluationOptions,
+  ConditionEvaluatorReporter,
+} from "../policies/engines/condition-evaluator-reporter";
+import type { PolicyEvent, PolicyReporter } from "./policy-reporter";
+import { SilentPolicyReporter } from "./silent-policy-reporter";
+
+export interface CoreObservabilityConfig {
+  readonly reporter?: PolicyReporter;
+}
+
+export interface CoreConfigOptions {
+  readonly observability?: CoreObservabilityConfig;
+}
+
+function reportSafely(
+  policyReporter: PolicyReporter,
+  event: PolicyEvent,
+): void {
+  try {
+    policyReporter.report(event);
+  } catch {
+    // Falhas de telemetria nao podem interromper o fluxo de dominio.
+  }
+}
+
+/**
+ * Centraliza a configuracao pura do core sem depender de implementacoes
+ * concretas de logging, tracing ou report.
+ */
+export class CoreConfig {
+  readonly #initialReporter: PolicyReporter;
+  #currentReporter: PolicyReporter;
+
+  constructor(options: CoreConfigOptions = {}) {
+    const reporter =
+      options.observability?.reporter ?? new SilentPolicyReporter();
+    this.#initialReporter = reporter;
+    this.#currentReporter = reporter;
+  }
+
+  configure(options: CoreConfigOptions): this {
+    const reporter = options.observability?.reporter;
+    if (reporter) {
+      this.#currentReporter = reporter;
+    }
+    return this;
+  }
+
+  // Restores the reporter captured at construction time.
+  reset(): this {
+    this.#currentReporter = this.#initialReporter;
+    return this;
+  }
+
+  getPolicyReporter(): PolicyReporter {
+    return this.#currentReporter;
+  }
+
+  getConditionEvaluationOptions(
+    engineVersion: number,
+  ): ConditionEvaluationOptions {
+    return {
+      reporter: this.#bridgeToConditionReporter(this.#currentReporter),
+      engineVersion,
+    };
+  }
+
+  #bridgeToConditionReporter(
+    policyReporter: PolicyReporter,
+  ): ConditionEvaluatorReporter {
+    return {
+      warn(report) {
+        reportSafely(policyReporter, {
+          kind: "condition-eval",
+          ...report,
+        } satisfies PolicyEvent);
+      },
+      error(report) {
+        reportSafely(policyReporter, {
+          kind: "condition-eval",
+          ...report,
+        } satisfies PolicyEvent);
+      },
+    };
+  }
+}

package/src/core/config/index.ts

@@ -0,0 +1,12 @@
+export type { CoreConfigOptions, CoreObservabilityConfig } from "./core-config";
+export { CoreConfig } from "./core-config";
+export { coreConfig } from "./core-config.instance";
+export type {
+  PolicyEvent,
+  PolicyReporter,
+  ConditionEvalEvent,
+  PolicyResolutionEvent,
+  PolicyEvaluationFailedEvent,
+  PolicyEvaluationCompletedEvent,
+} from "./policy-reporter";
+export { SilentPolicyReporter } from "./silent-policy-reporter";

package/src/core/config/policy-reporter.ts

@@ -0,0 +1,60 @@
+import type { ConditionEvaluationReport } from "../policies/engines/condition-evaluator-reporter";
+import type {
+  PolicyDecisionId,
+  PolicyDefinitionId,
+} from "../policies/policy-ids";
+
+// ─── Event kinds ─────────────────────────────────────────────────────────────
+
+export type ConditionEvalEvent = ConditionEvaluationReport & {
+  readonly kind: "condition-eval";
+};
+
+export interface PolicyResolutionEvent {
+  readonly kind: "policy-resolution";
+  readonly level: "info";
+  readonly policyKey: string;
+  readonly definitionId: PolicyDefinitionId;
+  readonly policyVersion: string;
+  readonly engineKind: "GATE" | "COMPUTE";
+  readonly engineVersion: number;
+  readonly occurredAt: Date;
+}
+
+export interface PolicyEvaluationFailedEvent {
+  readonly kind: "policy-evaluation-failed";
+  readonly level: "error";
+  readonly policyKey: string | undefined;
+  readonly errorKind: string;
+  readonly message: string;
+  readonly cause: string;
+  readonly occurredAt: Date;
+}
+
+export interface PolicyEvaluationCompletedEvent {
+  readonly kind: "policy-evaluation-completed";
+  readonly level: "info";
+  readonly policyKey: string;
+  readonly decisionId: PolicyDecisionId;
+  readonly engineKind: "GATE" | "COMPUTE";
+  readonly occurredAt: Date;
+}
+
+export type PolicyEvent =
+  | ConditionEvalEvent
+  | PolicyResolutionEvent
+  | PolicyEvaluationFailedEvent
+  | PolicyEvaluationCompletedEvent;
+
+// ─── Reporter interface ───────────────────────────────────────────────────────
+
+export interface PolicyReporter {
+  report(event: PolicyEvent): void;
+}
+
+// ─── Re-export only what external consumers need for event construction ───────
+
+export type {
+  ConditionEvaluationReport,
+  ConditionEvaluationReportTag,
+} from "../policies/engines/condition-evaluator-reporter";

package/src/core/config/silent-policy-reporter.ts

@@ -0,0 +1,5 @@
+import type { PolicyReporter } from "./policy-reporter";
+
+export class SilentPolicyReporter implements PolicyReporter {
+  report(_event: Parameters<PolicyReporter["report"]>[0]): void {}
+}

package/src/core/domain/entity.ts

@@ -0,0 +1,69 @@
+import { InvariantViolationException } from "../exceptions/invariant-violation-exception";
+import { assertValidAggregateVersion } from "../shared/aggregate-version";
+import { assertValidDate, cloneDate } from "../shared/temporal-guards";
+import { type ContractVersion, version } from "../versioning/version";
+
+interface EntityState<TIdentifier> {
+  readonly id: TIdentifier;
+  readonly createdAt: Date;
+  readonly updatedAt: Date;
+  readonly aggregateVersion: number;
+}
+
+@version("1.0")
+abstract class Entity<TIdentifier> {
+  public static readonly CONTRACT_VERSION: ContractVersion;
+
+  private readonly _id: TIdentifier;
+  private readonly _createdAt: Date;
+  private _updatedAt: Date;
+  private _aggregateVersion: number;
+
+  protected constructor(state: EntityState<TIdentifier>) {
+    assertValidDate("createdAt", state.createdAt);
+    assertValidDate("updatedAt", state.updatedAt);
+    assertValidAggregateVersion(state.aggregateVersion);
+
+    if (state.updatedAt.getTime() < state.createdAt.getTime()) {
+      throw new InvariantViolationException(
+        "updatedAt cannot be earlier than createdAt",
+      );
+    }
+
+    this._id = state.id;
+    this._createdAt = cloneDate(state.createdAt);
+    this._updatedAt = cloneDate(state.updatedAt);
+    this._aggregateVersion = state.aggregateVersion;
+  }
+
+  public get id(): TIdentifier {
+    return this._id;
+  }
+
+  public get createdAt(): Date {
+    return cloneDate(this._createdAt);
+  }
+
+  public get updatedAt(): Date {
+    return cloneDate(this._updatedAt);
+  }
+
+  public get aggregateVersion(): number {
+    return this._aggregateVersion;
+  }
+
+  public get contractVersion(): ContractVersion {
+    return Entity.CONTRACT_VERSION;
+  }
+
+  protected markAsModified(updatedAt: Date = new Date()): number {
+    assertValidDate("updatedAt", updatedAt);
+
+    this._updatedAt = cloneDate(updatedAt);
+    this._aggregateVersion += 1;
+
+    return this._aggregateVersion;
+  }
+}
+
+export { Entity, type EntityState };

package/src/core/domain/rulesets/entity-ruleset.contracts.ts

@@ -0,0 +1,16 @@
+import { type Ruleset, type RulesetId } from "./ruleset.contracts";
+import { DomainException } from "../../exceptions/domain-exception";
+
+interface CreationRuleset<TData> extends Ruleset {
+  validate(data: TData): void;
+}
+
+type InvariantRuleset = Ruleset;
+
+export {
+  type CreationRuleset,
+  DomainException,
+  type InvariantRuleset,
+  type Ruleset,
+  type RulesetId,
+};

package/src/core/domain/rulesets/ruleset-registry.ts

@@ -0,0 +1,71 @@
+import { DomainException } from "../../exceptions/domain-exception";
+import {
+  type Ruleset,
+  type RulesetRegistry as RulesetRegistryContract,
+} from "./ruleset.contracts";
+
+class RulesetRegistryError extends DomainException {}
+
+function parseVersion(id: string): [number, number] {
+  const atIdx = id.lastIndexOf("@");
+  const versionStr = id.slice(atIdx + 1);
+  const [major, minor] = versionStr.split(".").map(Number);
+  return [major, minor];
+}
+
+class RulesetRegistry implements RulesetRegistryContract {
+  private readonly _store = new Map<string, Ruleset>();
+  private _sealed = false;
+
+  register(ruleset: Ruleset): void {
+    if (this._sealed) {
+      throw new RulesetRegistryError(
+        "Registry is sealed. No new rulesets can be registered.",
+      );
+    }
+    if (this._store.has(ruleset.id)) {
+      throw new RulesetRegistryError(
+        `Ruleset with id "${ruleset.id}" is already registered.`,
+      );
+    }
+    this._store.set(ruleset.id, ruleset);
+  }
+
+  seal(): void {
+    this._sealed = true;
+  }
+
+  get<T extends Ruleset>(id: string): T {
+    const ruleset = this._store.get(id);
+    if (!ruleset) {
+      const available = Array.from(this._store.keys()).join(", ");
+      throw new RulesetRegistryError(
+        `Ruleset "${id}" not found. Available: [${available}]`,
+      );
+    }
+    return ruleset as T;
+  }
+
+  getCurrent<T extends Ruleset>(prefix: string): T {
+    const matchingEntries = Array.from(this._store.entries()).filter(([key]) =>
+      key.startsWith(prefix + "@"),
+    );
+
+    if (matchingEntries.length === 0) {
+      throw new RulesetRegistryError(
+        `No rulesets found with prefix "${prefix}".`,
+      );
+    }
+
+    const sorted = matchingEntries.sort(([a], [b]) => {
+      const [aMajor, aMinor] = parseVersion(a);
+      const [bMajor, bMinor] = parseVersion(b);
+      if (aMajor !== bMajor) return aMajor - bMajor;
+      return aMinor - bMinor;
+    });
+
+    return sorted[sorted.length - 1][1] as T;
+  }
+}
+
+export { RulesetRegistry };

package/src/core/domain/rulesets/ruleset.contracts.ts

@@ -0,0 +1,15 @@
+type RulesetId = `${string}@${number}.${number}`;
+
+interface Ruleset {
+  readonly id: RulesetId;
+  readonly description: string;
+}
+
+interface RulesetRegistry {
+  register(ruleset: Ruleset): void;
+  seal(): void;
+  get<T extends Ruleset>(id: string): T;
+  getCurrent<T extends Ruleset>(prefix: string): T;
+}
+
+export { type Ruleset, type RulesetId, type RulesetRegistry };

package/src/core/domain/rulesets/value-object-ruleset.contracts.ts

@@ -0,0 +1,13 @@
+import { DomainException } from "../../exceptions/domain-exception";
+import { type Ruleset, type RulesetId } from "./ruleset.contracts";
+
+interface ValueObjectRuleset<T> extends Ruleset {
+  validate(value: T): void;
+}
+
+export {
+  DomainException,
+  type Ruleset,
+  type RulesetId,
+  type ValueObjectRuleset,
+};

package/src/core/domain/temporal/index.ts

@@ -0,0 +1,18 @@
+export {
+  assertTransactionTime,
+  createTransactionTime,
+  type CreateTransactionTimeInput,
+  type TransactionTime,
+} from "./transaction-time";
+export { contains, isClosed, isOpen, overlaps } from "./temporal-range";
+export {
+  createTemporalSnapshot,
+  type CreateTemporalSnapshotInput,
+  type TemporalSnapshot,
+} from "./temporal-snapshot";
+export {
+  assertValidTime,
+  createValidTime,
+  type CreateValidTimeInput,
+  type ValidTime,
+} from "./valid-time";

package/src/core/domain/temporal/temporal-range.ts

@@ -0,0 +1,53 @@
+import { assertValidDate } from "../../shared/temporal-guards";
+
+import { assertValidTime, type ValidTime } from "./valid-time";
+
+/**
+ * Checks whether a temporal range is "open" (has no end date).
+ * Useful for identifying information that is still in effect / active.
+ */
+function isOpen(range: ValidTime): boolean {
+  assertValidTime(range, "range");
+
+  return range.to === undefined;
+}
+
+/**
+ * Checks whether a temporal range is "closed" (has a defined end date).
+ */
+function isClosed(range: ValidTime): boolean {
+  return !isOpen(range);
+}
+
+/**
+ * Checks whether a specific date is contained within the temporal range.
+ * The lower bound (`from`) is inclusive, while the upper bound (`to`) is exclusive.
+ */
+function contains(range: ValidTime, date: Date): boolean {
+  assertValidTime(range, "range");
+  assertValidDate("date", date);
+
+  const fromTime = range.from.getTime();
+  const toTime = range.to?.getTime() ?? Number.POSITIVE_INFINITY;
+  const targetTime = date.getTime();
+
+  return targetTime >= fromTime && targetTime < toTime;
+}
+
+/**
+ * Checks whether two temporal ranges overlap at any point.
+ * Useful for validating whether a new rule conflicts with an existing one.
+ */
+function overlaps(left: ValidTime, right: ValidTime): boolean {
+  assertValidTime(left, "left");
+  assertValidTime(right, "right");
+
+  const leftFrom = left.from.getTime();
+  const leftTo = left.to?.getTime() ?? Number.POSITIVE_INFINITY;
+  const rightFrom = right.from.getTime();
+  const rightTo = right.to?.getTime() ?? Number.POSITIVE_INFINITY;
+
+  return leftFrom < rightTo && rightFrom < leftTo;
+}
+
+export { contains, isClosed, isOpen, overlaps };

package/src/core/domain/temporal/temporal-snapshot.ts

@@ -0,0 +1,47 @@
+import { type DeepReadonly, makeImmutable } from "../../shared/immutable";
+
+import {
+  createTransactionTime,
+  type CreateTransactionTimeInput,
+  type TransactionTime,
+} from "./transaction-time";
+import {
+  createValidTime,
+  type CreateValidTimeInput,
+  type ValidTime,
+} from "./valid-time";
+
+/**
+ * Pairs a domain datum with its time dimensions (Business and Transaction).
+ * It is the representation of an entry in the append-only (historical) table.
+ */
+interface TemporalSnapshot<T> {
+  /** The data or state captured by the snapshot. */
+  readonly data: DeepReadonly<T>;
+  /** Period during which this datum was valid in the real world. */
+  readonly validTime: ValidTime;
+  /** Period during which this record was the state known to the system. */
+  readonly txTime: TransactionTime;
+}
+
+interface CreateTemporalSnapshotInput<T> {
+  readonly data: T;
+  readonly validTime: CreateValidTimeInput;
+  readonly txTime: CreateTransactionTimeInput;
+}
+
+function createTemporalSnapshot<T>(
+  input: CreateTemporalSnapshotInput<T>,
+): TemporalSnapshot<T> {
+  return makeImmutable({
+    data: input.data,
+    validTime: createValidTime(input.validTime),
+    txTime: createTransactionTime(input.txTime),
+  });
+}
+
+export {
+  createTemporalSnapshot,
+  type CreateTemporalSnapshotInput,
+  type TemporalSnapshot,
+};