@cullet/erp-core 1.0.11 → 1.2.0

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

@@ -1,8 +1,31 @@
 import { type ContractVersion, version } from "../versioning/version.js";
 import type { Result } from "../result/result.js";
 
+import type { LoggerPort } from "./ports/logger.port.js";
+import type { MetricsPort } from "./ports/metrics.port.js";
+import type { TracerPort } from "./ports/tracer.port.js";
+
 type MaybePromise<T> = T | Promise<T>;
 
+/**
+ * Observability adapters a use case may opt into.
+ *
+ * All fields are optional: a use case that provides none keeps the plain
+ * `input → Result` behavior with zero overhead. When provided, {@link UseCase.run}
+ * instruments every execution around `execute()` — opening a span, recording
+ * duration, counting outcomes, and logging business/unexpected failures.
+ */
+interface UseCaseObservability {
+    readonly logger?: LoggerPort;
+    readonly metrics?: MetricsPort;
+    readonly tracer?: TracerPort;
+}
+
+const EXECUTION_COUNTER = "use_case.executions";
+const DURATION_HISTOGRAM = "use_case.duration_ms";
+
+type ExecutionOutcome = "ok" | "error" | "exception";
+
 @version("1.0")
 abstract class UseCase<
     Input = void,
@@ -14,11 +37,119 @@ abstract class UseCase<
         return UseCase.CONTRACT_VERSION;
     }
 
+    /**
+     * Runs the use case.
+     *
+     * `run()` is the single seam every use case crosses, so it is where
+     * cross-cutting instrumentation lives. When {@link observability} exposes
+     * any adapter, the call to `execute()` is wrapped with tracing, metrics and
+     * failure logging; otherwise it delegates directly with no overhead.
+     *
+     * Observability is strictly side-effecting: a misbehaving adapter never
+     * changes the business result nor masks a thrown error — its own failures
+     * are swallowed.
+     */
     public async run(input: Input): Promise<Output> {
-        return await this.execute(input);
+        const observability = this.observability();
+        if (
+            !observability.logger &&
+            !observability.metrics &&
+            !observability.tracer
+        ) {
+            return await this.execute(input);
+        }
+
+        return await this.runInstrumented(input, observability);
+    }
+
+    /**
+     * Adapters used to instrument {@link run}. Override to opt a use case into
+     * tracing/metrics/logging. Returns an empty object by default, which keeps
+     * the plain delegating behavior.
+     */
+    protected observability(): UseCaseObservability {
+        return {};
+    }
+
+    /**
+     * Stable identity used for span names and metric labels. Defaults to the
+     * runtime class name; override when bundling/minification would otherwise
+     * erase a meaningful name.
+     */
+    protected get useCaseName(): string {
+        return this.constructor.name;
     }
 
     protected abstract execute(input: Input): MaybePromise<Output>;
+
+    private async runInstrumented(
+        input: Input,
+        observability: UseCaseObservability,
+    ): Promise<Output> {
+        const { logger, metrics, tracer } = observability;
+        const name = this.useCaseName;
+        const span = safely(() =>
+            tracer?.startSpan(name, { "use_case.name": name }),
+        );
+        const startedAt = Date.now();
+
+        try {
+            const output = await this.execute(input);
+            const outcome: ExecutionOutcome = output.isOk() ? "ok" : "error";
+
+            if (outcome === "error") {
+                safely(() =>
+                    logger?.warn(`${name} returned a business error`, {
+                        useCase: name,
+                    }),
+                );
+            }
+            safely(() => span?.setAttribute("use_case.outcome", outcome));
+            safely(() =>
+                metrics?.counter(EXECUTION_COUNTER, 1, {
+                    useCase: name,
+                    outcome,
+                }),
+            );
+
+            return output;
+        } catch (error) {
+            safely(() =>
+                logger?.error(`${name} threw an unexpected error`, {
+                    useCase: name,
+                }),
+            );
+            safely(() => span?.setAttribute("use_case.outcome", "exception"));
+            safely(() => span?.recordException(error));
+            safely(() =>
+                metrics?.counter(EXECUTION_COUNTER, 1, {
+                    useCase: name,
+                    outcome: "exception",
+                }),
+            );
+
+            throw error;
+        } finally {
+            safely(() =>
+                metrics?.histogram(DURATION_HISTOGRAM, Date.now() - startedAt, {
+                    useCase: name,
+                }),
+            );
+            safely(() => span?.end());
+        }
+    }
+}
+
+/**
+ * Invokes an observability side effect, isolating any adapter failure so it
+ * cannot alter the use case outcome.
+ */
+function safely<R>(effect: () => R): R | undefined {
+    try {
+        return effect();
+    } catch {
+        return undefined;
+    }
 }
 
-export { type MaybePromise, UseCase };
+export { type MaybePromise, UseCase, type UseCaseObservability };

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

@@ -0,0 +1,7 @@
+export {
+    type CreationRuleset,
+    type InvariantRuleset,
+} from "./entity-ruleset.contracts.js";
+export { RulesetRegistry } from "./ruleset-registry.js";
+export { type Ruleset, type RulesetId } from "./ruleset.contracts.js";
+export { type ValueObjectRuleset } from "./value-object-ruleset.contracts.js";

package/src/core/domain/uuid-identifier.ts

@@ -0,0 +1,72 @@
+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.
+ *
+ * A domain typically has many of these — `OrderId`, `CustomerId`, `InvoiceId` —
+ * all wrapping the same `string` shape. Two problems follow: the UUID format
+ * check gets copy-pasted into every one, and because the wrapped shape is
+ * identical, TypeScript's structural typing would happily accept an `OrderId`
+ * where a `CustomerId` is expected. `UuidIdentifier` solves both: the format
+ * lives here once ({@link isValid}), and the `TBrand` phantom tag makes each
+ * subtype nominally distinct so the ids cannot be swapped for one another.
+ *
+ * It deliberately does not impose a factory. Identifiers vary in how they
+ * report an invalid value (their own exception type, their own message), so a
+ * concrete id adds a validating `create` that calls {@link isValid} plus a
+ * `reconstitute` that trusts an already-persisted value:
+ *
+ * ```ts
+ * class OrderId extends UuidIdentifier<"OrderId"> {
+ *   private constructor(value: string) { super(value); }
+ *   static create(raw: string): OrderId {
+ *     if (!UuidIdentifier.isValid(raw)) throw new InvalidOrderIdError(raw);
+ *     return new OrderId(raw);
+ *   }
+ *   static reconstitute(value: string): OrderId { return new OrderId(value); }
+ * }
+ * ```
+ *
+ * @typeParam TBrand - A unique string literal that nominally tags the subtype.
+ */
+abstract class UuidIdentifier<
+    TBrand extends string = string,
+> extends ValueObject<string, string> {
+    /**
+     * Phantom brand. Never assigned at runtime (`declare`), it exists only so
+     * two identifiers with different brands are not interchangeable at the type
+     * level despite sharing the same `string` value.
+     */
+    protected declare readonly __brand: TBrand;
+
+    protected constructor(value: string) {
+        super(value);
+    }
+
+    public toPrimitive(): string {
+        return this.value;
+    }
+
+    /** The wrapped UUID string — convenient for logging and interpolation. */
+    public toString(): string {
+        return this.value;
+    }
+
+    /**
+     * Whether `candidate` is a canonical UUID (versions 1–5). The single source
+     * of truth for the format; concrete identifiers call this from `create`.
+     */
+    public static isValid(candidate: string): boolean {
+        return UUID_PATTERN.test(candidate);
+    }
+}
+
+export { UuidIdentifier };

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

@@ -1,6 +1,21 @@
+import { PluginManager } from "../plugins/index.js";
 import { type DeepReadonly, makeImmutable } from "../shared/immutable.js";
 import { type ContractVersion, version } from "../versioning/version.js";
 
+/**
+ * Extension point for value-object equality. A plugin implementing this
+ * contract overrides how any two value objects are compared, letting the host
+ * application swap in a structural comparator (e.g. `lodash.isEqual` over the
+ * wrapped `value`) without every value object having to implement `equals` by
+ * hand.
+ */
+type ValueObjectPluginContract = {
+    equals: (
+        a: ValueObject<unknown, unknown>,
+        b: ValueObject<unknown, unknown>,
+    ) => boolean;
+};
+
 /**
  * Base class for value objects — domain concepts defined entirely by their
  * contents, with no identity of their own. Two value objects are
@@ -20,6 +35,15 @@ import { type ContractVersion, version } from "../versioning/version.js";
 abstract class ValueObject<T, P> {
     declare public static readonly CONTRACT_VERSION: ContractVersion;
 
+    /**
+     * Registry of equality plugins shared by every value object. Empty by
+     * 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.
+     */
+    public static readonly plugins =
+        new PluginManager<ValueObjectPluginContract>();
+
     /** The wrapped data, deep-frozen so it can never be mutated after construction. */
     public readonly value: DeepReadonly<T>;
 
@@ -65,11 +89,19 @@ abstract class ValueObject<T, P> {
 
     /**
      * Compares this value object with another by content. Because value objects
-     * carry no identity, subclasses implement equality over the wrapped data
-     * (typically the primitive form), so two independently constructed instances
-     * holding the same data are considered equal.
+     * carry no identity, two independently constructed instances holding the
+     * 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`.
+     * Subclasses may still override for a faster or domain-specific comparison.
      */
-    public abstract equals(other: this): boolean;
+    public equals(other: this): boolean {
+        return ValueObject.plugins.invoke("equals", [this, other], {
+            fallback: (a, b) =>
+                JSON.stringify(a.value) === JSON.stringify(b.value),
+        });
+    }
 
     /**
      * Projects the value object down to a plain, serializable primitive form —
@@ -78,4 +110,4 @@ abstract class ValueObject<T, P> {
     public abstract toPrimitive(): P;
 }
 
-export { type DeepReadonly, ValueObject };
+export { type DeepReadonly, ValueObject, type ValueObjectPluginContract };

package/src/core/exceptions/index.ts

@@ -0,0 +1,13 @@
+export { BusinessRuleViolationException } from "./business-rule-violation-exception.js";
+export { DomainException } from "./domain-exception.js";
+export { EntityNotFoundException } from "./entity-not-found-exception.js";
+export { InvalidStateTransitionException } from "./invalid-state-transition-exception.js";
+export { InvariantViolationException } from "./invariant-violation-exception.js";
+export { ValidationCode } from "./validation-code.js";
+export {
+    InvalidValueException,
+    MultipleValidationException,
+    ValidationException,
+    type ValidationViolation,
+} from "./validation-exception.js";
+export { ValidationField } from "./validation-field.js";

package/src/core/index.ts

@@ -1,15 +1,18 @@
 export * from "./errors/index.js";
-export * from "./exceptions/validation-field.js";
-export type {
-    LogPayload,
-    LoggerPort,
-    MetricLabels,
-    MetricsPort,
-    TraceAttributeValue,
-    TraceSpan,
-    TracerPort,
-} from "./application/index.js";
-export { mapPolicyEvaluationError } from "./application/policy-error-mapper.js";
+export * from "./exceptions/index.js";
+export * from "./application/index.js";
 export { Entity, type EntityState } from "./domain/entity.js";
-export { ValueObject, type DeepReadonly } from "./domain/value-object.js";
+export { UuidIdentifier } from "./domain/uuid-identifier.js";
+export {
+    ValueObject,
+    type DeepReadonly,
+    type ValueObjectPluginContract,
+} from "./domain/value-object.js";
+export * from "./domain/rulesets/index.js";
+export * from "./plugins/index.js";
+export * from "./versioning/index.js";
+// NOTE: `./policies` re-exports Result/Ok/Err/Outcome/CommonOutcomeStatus and
+// transitively pulls in `zod` (the gate/compute engines). Consumers that only
+// need the zod-free primitives should import the dedicated subpaths
+// (`@cullet/erp-core/{domain,result,exceptions,rulesets,versioning,plugins}`).
 export * from "./policies/index.js";

package/src/core/plugins/index.ts

@@ -0,0 +1,7 @@
+export { PluginManager } from "./plugin.js";
+export type {
+    BasePlugin,
+    InvokeOptions,
+    PipelineReducer,
+    PluginContract,
+} from "./types.js";

package/src/core/plugins/plugin.ts

@@ -0,0 +1,99 @@
+import {
+    type BasePlugin,
+    type InvokeOptions,
+    type PipelineReducer,
+    type PluginContract,
+} from "./types.js";
+
+/**
+ * Registry that holds a set of plugins implementing a shared {@link PluginContract}
+ * and resolves which of them answer a given extension point.
+ *
+ * Plugins are kept sorted by priority (descending). For a given method,
+ * {@link invoke} either delegates to the highest-priority enabled plugin
+ * (`'first'`) or folds every enabled plugin into a single value (`'pipeline'`).
+ * When no plugin is enabled, the supplied `fallback` runs instead, so the host
+ * always has defined behaviour even with an empty registry.
+ *
+ * @typeParam P - The plugin contract this manager coordinates.
+ */
+class PluginManager<P extends PluginContract> {
+    /** Internal list, kept sorted by priority (desc). */
+    private plugins: (P & BasePlugin)[] = [];
+
+    /** Registers one or more plugins and re-sorts by priority. */
+    public register(...plugins: (P & BasePlugin)[]): void {
+        this.plugins.push(...plugins);
+        this.reorder();
+    }
+
+    /** Removes a previously registered plugin by name. */
+    public unregister(name: string): void {
+        this.plugins = this.plugins.filter((p) => p.name !== name);
+    }
+
+    /** Enables a registered plugin by name. */
+    public enable(name: string): void {
+        const plugin = this.plugins.find((p) => p.name === name);
+        if (plugin) plugin.enabled = true;
+    }
+
+    /** Disables a registered plugin by name (without removing it). */
+    public disable(name: string): void {
+        const plugin = this.plugins.find((p) => p.name === name);
+        if (plugin) plugin.enabled = false;
+    }
+
+    /** Lists enabled plugins only, already in priority order. */
+    public list(): readonly (P & BasePlugin)[] {
+        return this.plugins.filter((p) => p.enabled !== false);
+    }
+
+    /**
+     * Resolves `method` against the registered plugins.
+     *
+     * In `'first'` mode the highest-priority enabled plugin that implements
+     * `method` answers. In `'pipeline'` mode every enabled plugin runs and the
+     * results are folded with `reducer` (defaults to "keep the last result").
+     * When no enabled plugin implements `method`, `fallback` is called.
+     */
+    public invoke<K extends keyof P>(
+        method: K,
+        args: Parameters<P[K]>,
+        opts: InvokeOptions<P, K>,
+    ): ReturnType<P[K]> {
+        const { mode = "first", fallback, reducer } = opts;
+        const enabled = this.list().filter((p) => method in p) as Array<
+            P & BasePlugin
+        >;
+
+        if (enabled.length === 0) {
+            return (fallback as P[K])(...args);
+        }
+
+        if (mode === "first") {
+            const fn = enabled[0][method] as P[K];
+            return fn(...args);
+        }
+
+        const defaultReducer: PipelineReducer<ReturnType<P[K]>, P> = (
+            _,
+            curr,
+        ) => curr;
+        const red = reducer ?? defaultReducer;
+
+        let acc: ReturnType<P[K]> = enabled[0][method]!(...args);
+        enabled.slice(1).forEach((plugin, idx) => {
+            const res = plugin[method]!(...args);
+            acc = red(acc, res, plugin, idx + 1);
+        });
+        return acc;
+    }
+
+    /** Re-sorts the internal list by priority (desc; default priority = 0). */
+    private reorder(): void {
+        this.plugins.sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+    }
+}
+
+export { PluginManager };

package/src/core/plugins/types.ts

@@ -0,0 +1,53 @@
+/**
+ * Common shape every plugin shares, regardless of the contract it implements.
+ * Carries the metadata the {@link PluginManager} uses to identify, order and
+ * toggle plugins.
+ */
+interface BasePlugin {
+    /** Unique identifier, used for logs / debugging and for enable/disable. */
+    readonly name: string;
+    /** Weight; the highest priority wins (default = 0). */
+    readonly priority?: number;
+    /** Shortcut to disable a plugin without removing it. */
+    enabled?: boolean;
+}
+
+/**
+ * A plugin contract is a record whose values are the methods plugins may
+ * implement for a given extension point.
+ *
+ * `any` here is intentional: it is the only way to express the constraint
+ * "a record whose values are arbitrary functions". Using `unknown` for the
+ * parameters breaks assignment of concrete contracts by contravariance —
+ * TypeScript rejects functions with specific parameters as a subtype of
+ * `(...args: unknown[]) => unknown`.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type PluginContract = Record<string, (...args: any[]) => any>;
+
+/**
+ * Reducer used in `pipeline` mode to combine the result of each plugin into a
+ * single accumulated value.
+ */
+type PipelineReducer<R, P extends PluginContract> = (
+    accumulated: R,
+    current: R,
+    plugin: P & BasePlugin,
+    index: number,
+) => R;
+
+/** Options accepted by {@link PluginManager.invoke}. */
+interface InvokeOptions<P extends PluginContract, K extends keyof P> {
+    /**
+     * `'first'`    → returns the first enabled plugin with the highest priority.
+     * `'pipeline'` → runs every enabled plugin, combining results via `reducer`.
+     * default = `'first'`.
+     */
+    mode?: "first" | "pipeline";
+    /** Executed when no plugin is enabled for the method. */
+    fallback: P[K];
+    /** Reducer used only when `mode = "pipeline"`. */
+    reducer?: PipelineReducer<ReturnType<P[K]>, P>;
+}
+
+export type { BasePlugin, InvokeOptions, PipelineReducer, PluginContract };

package/src/core/versioning/index.ts

@@ -0,0 +1,14 @@
+export {
+    buildDomainEventContractVersions,
+    createDomainEventEnvelope,
+    type CreateDomainEventEnvelopeInput,
+    type DomainEventContractSelection,
+    type DomainEventContractVersions,
+    type DomainEventEnvelope,
+} from "./domain-event-contracts.js";
+export {
+    CONTRACT_VERSION_PROPERTY,
+    type ContractVersion,
+    version,
+    type VersionedTarget,
+} from "./version.js";

package/src/domain/index.ts

@@ -0,0 +1,7 @@
+export { Entity, type EntityState } from "../core/domain/entity.js";
+export { UuidIdentifier } from "../core/domain/uuid-identifier.js";
+export {
+    type DeepReadonly,
+    ValueObject,
+    type ValueObjectPluginContract,
+} from "../core/domain/value-object.js";

package/src/examples/application/cancel-order.example.ts

@@ -0,0 +1,124 @@
+/**
+ * End-to-end reference: a concrete {@link Command} wiring a
+ * {@link ResultRepository} and a {@link PolicyPort} together.
+ *
+ * Flow: load the aggregate → ask a declarative policy whether the action is
+ * allowed → mutate and persist. Every recoverable failure (infra error from
+ * the repository, a policy `DENY`, a missing aggregate, an optimistic-locking
+ * conflict on save) is returned as a typed `Result.err(...)` rather than
+ * thrown — the "errors as values" contract that `Command`/`UseCase` enforce.
+ *
+ * Consumers import these symbols from the package root (`@cullet/erp-core`);
+ * inside the kit we use relative paths so the example stays compilable and
+ * test-covered, guarding the snippet in the README/KIT_CONTEXT against rot.
+ */
+import { Command, type CommandInput } from "../../core/application/index.js";
+import type {
+    PolicyPort,
+    ResultRepository,
+} from "../../core/application/index.js";
+import { AuthorizationError } from "../../core/errors/authorization-error.js";
+import { NotFoundError } from "../../core/errors/not-found-error.js";
+import {
+    asPolicyDecisionId,
+    asSchoolId,
+    asTenantId,
+} from "../../core/policies/index.js";
+import { Result } from "../../core/result/result.js";
+
+// ─── Minimal domain ─────────────────────────────────────────────────────────
+
+type OrderStatus = "OPEN" | "CANCELLED";
+
+interface Order {
+    readonly id: string;
+    readonly status: OrderStatus;
+}
+
+// ─── Command contract ────────────────────────────────────────────────────────
+
+// `CommandInput` forces every mutation to record *who* triggered it.
+interface CancelOrderInput extends CommandInput {
+    readonly orderId: string;
+    readonly tenantId: string;
+    readonly schoolId: string;
+}
+
+type CancelOrderError = NotFoundError | AuthorizationError;
+
+// ─── The use case ─────────────────────────────────────────────────────────────
+
+class CancelOrder extends Command<
+    CancelOrderInput,
+    Result<Order, CancelOrderError>
+> {
+    constructor(
+        private readonly orders: ResultRepository<
+            Order,
+            string,
+            CancelOrderError
+        >,
+        private readonly policies: PolicyPort,
+    ) {
+        super();
+    }
+
+    protected async execute(
+        input: CancelOrderInput,
+    ): Promise<Result<Order, CancelOrderError>> {
+        // 1. Load the aggregate. Infra failures stay in band as Result.err.
+        const found = await this.orders.findById(input.orderId);
+        if (found.isErr()) {
+            return found;
+        }
+
+        const order = found.getOrThrow();
+        if (!order) {
+            return Result.err(
+                new NotFoundError("Order", { id: input.orderId }),
+            );
+        }
+
+        // 2. Decide via a declarative policy (a GATE returns ALLOW/DENY).
+        const evaluated = await this.policies.evaluate({
+            decisionId: asPolicyDecisionId(input.orderId),
+            policyKey: "order.cancel",
+            scopeChain: [],
+            contextVersion: 1,
+            seed: {
+                tenantId: asTenantId(input.tenantId),
+                schoolId: asSchoolId(input.schoolId),
+                fields: { orderStatus: order.status },
+            },
+        });
+        if (evaluated.isErr()) {
+            return evaluated;
+        }
+
+        const result = evaluated.getOrThrow();
+        if (result.kind === "GATE" && result.decision.status === "DENY") {
+            return Result.err(
+                AuthorizationError.policyDenied({
+                    action: "order.cancel",
+                    resource: { type: "Order", id: order.id },
+                    policyId: result.ref.definitionId,
+                    policyVersion: Number(result.ref.policyVersion),
+                    evaluatedAtIso: result.evaluatedAt.toISOString(),
+                }),
+            );
+        }
+
+        // 3. Mutate and persist. A version conflict on save also surfaces as
+        //    Result.err — never an exception crossing the boundary.
+        const cancelled: Order = { ...order, status: "CANCELLED" };
+        const saved = await this.orders.save(cancelled);
+        if (saved.isErr()) {
+            return saved;
+        }
+
+        return Result.ok(cancelled);
+    }
+}
+
+export { CancelOrder };
+export type { CancelOrderError, CancelOrderInput, Order, OrderStatus };