@cullet/erp-core 1.0.10 → 1.1.0

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

@@ -9,7 +9,25 @@ import type { AppErrorOptions } from "./types.js";
 // ValidationError
 // ─────────────────────────────────────────────────────────────────────────────
 
+/**
+ * Raised when a single input fails a validation rule — the canonical
+ * "this field is wrong, and here is why" error.
+ *
+ * It pins the offending `field` and a machine-readable `validationCode` into
+ * the metadata (merged ahead of any caller-supplied metadata) so an API layer
+ * can map the failure straight onto a form field without parsing the message.
+ * The fixed {@link ErrorCodes.validation} code lets callers catch all
+ * validation failures uniformly while still distinguishing the specific rule
+ * through `validationCode`.
+ */
 class ValidationError extends AppError {
+    /**
+     * @param field - The input that failed validation; surfaced as `metadata.field`.
+     * @param code - The specific rule that was violated; surfaced as `metadata.validationCode`.
+     * @param message - The developer-facing description of the failure.
+     * @param options - Optional cause, correlation ids, and extra metadata
+     *   (merged over the field/code metadata, never overwriting it by accident).
+     */
     constructor(
         field: ValidationField,
         code: ValidationCode,

package/src/core/index.ts

@@ -1,15 +1,6 @@
 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 "./application/index.js";
 export { Entity, type EntityState } from "./domain/entity.js";
 export { ValueObject, type DeepReadonly } from "./domain/value-object.js";
 export * from "./policies/index.js";

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

@@ -14,6 +14,15 @@ export class PolicyCatalog {
         readonly PolicyCatalogEntry[]
     >;
 
+    /**
+     * Indexes the given entries up front into two lookups — one per exact
+     * variant, one per policy key (the "family") — and validates them eagerly:
+     * a duplicate variant or an internally inconsistent family throws here, at
+     * wiring time, so a malformed catalog fails fast at startup rather than on
+     * the first evaluation.
+     *
+     * @throws {UnexpectedError} When two entries resolve to the same variant key.
+     */
     constructor(entries: readonly PolicyCatalogEntry[]) {
         const families = new Map<string, PolicyCatalogEntry[]>();
         const versionedMap = new Map<string, PolicyCatalogEntry>();
@@ -43,6 +52,14 @@ export class PolicyCatalog {
         this.entriesByKey = families;
     }
 
+    /**
+     * Returns the single entry for a key. Deliberately strict: if the key has
+     * more than one variant it errs rather than guessing, steering the caller to
+     * {@link getVersioned} or {@link getFamily}. Use this only when a key is
+     * known to be unambiguous.
+     *
+     * @returns `ok` with the entry, or `err` when the key is unknown or ambiguous.
+     */
     get(key: string): Result<PolicyCatalogEntry, string> {
         const familyResult = this.getFamily(key);
         if (familyResult.isErr()) {
@@ -64,6 +81,13 @@ export class PolicyCatalog {
         return Result.ok(entry);
     }
 
+    /**
+     * Returns every variant registered under a key — the whole "family". This is
+     * the lookup the evaluation pipeline uses, since a single key may host
+     * several engine/schema variants that the resolver then chooses between.
+     *
+     * @returns `ok` with the family (always non-empty), or `err` when the key is unknown.
+     */
     getFamily(key: string): Result<readonly PolicyCatalogEntry[], string> {
         const family = this.entriesByKey.get(key);
         if (!family) {
@@ -73,6 +97,16 @@ export class PolicyCatalog {
         return Result.ok(family);
     }
 
+    /**
+     * Resolves the one entry matching an exact variant — kind plus engine and
+     * payload-schema versions. Falls back to the sole family member when a key
+     * has exactly one entry and that entry declares no explicit version
+     * selector, so unversioned single-variant policies "just work" without the
+     * caller spelling out versions.
+     *
+     * @param params - The key and the variant coordinates to match on.
+     * @returns `ok` with the matching entry, or `err` when no variant matches.
+     */
     getVersioned(params: {
         readonly key: string;
         readonly kind: "GATE" | "COMPUTE";
@@ -114,10 +148,12 @@ export class PolicyCatalog {
         );
     }
 
+    /** Lists every registered variant across all keys — useful for introspection and diagnostics. */
     list(): readonly PolicyCatalogEntry[] {
         return Array.from(this.versionedEntries.values());
     }
 
+    /** Returns whether any variant is registered under the given key. */
     has(key: string): boolean {
         return this.entriesByKey.has(key);
     }

package/src/core/policies/resolver/policy-resolver.ts

@@ -14,6 +14,16 @@ import { Result } from "../../result/result.js";
  *   5. policyVersion descending (semver — final deterministic tiebreaker)
  */
 export class PolicyResolver {
+    /**
+     * Picks the single winning definition from an already-filtered candidate
+     * list by applying the class's ordering criteria in priority order. The sort
+     * runs over a copy, so the caller's array is left untouched, and the final
+     * semver tiebreaker guarantees the winner is fully deterministic — it never
+     * depends on the order the repository returned the candidates in.
+     *
+     * @param candidates - Definitions already filtered to match key, scope, and as-of.
+     * @returns `ok` with the highest-ranked definition, or `err` when the list is empty.
+     */
     resolveBest(
         candidates: readonly PolicyDefinition[],
     ): Result<PolicyDefinition, string> {

package/src/core/policies/service/policy-service.ts

@@ -36,6 +36,13 @@ import {
 
 // ─── Input ──────────────────────────────────────────────────────────────────
 
+/**
+ * Everything a single policy evaluation needs. `policyKey` names the policy,
+ * `scopeChain` narrows the search from most-specific to least-specific scope,
+ * `contextVersion` pins which context schema applies, and `seed` carries the
+ * raw facts the context builder expands. `decisionId` is the caller's
+ * idempotency/audit handle, echoed back on the result.
+ */
 export interface EvaluateInput {
     readonly decisionId: PolicyDecisionId;
     readonly policyKey: string;
@@ -44,11 +51,23 @@ export interface EvaluateInput {
     readonly seed: ContextSeed;
 }
 
+/**
+ * Cross-cutting knobs for a {@link PolicyService}: how the as-of instant is
+ * derived ({@link asOf}) and where evaluation telemetry is sent
+ * ({@link reporter}). Both are optional; the service defaults to a silent
+ * reporter so telemetry is opt-in.
+ */
 export interface PolicyServiceOptions {
     readonly asOf?: DeriveAsOfOptions;
     readonly reporter?: PolicyReporter;
 }
 
+/**
+ * The collaborators a {@link PolicyService} is wired with. Each is an injected
+ * port so the service stays storage- and engine-agnostic: the catalog defines
+ * the universe of policies, `defRepo` supplies their versioned definitions, the
+ * `resolver` picks the winning definition, and the engine registries execute it.
+ */
 export interface PolicyServiceParams {
     readonly catalog: PolicyCatalog;
     readonly contextBuilder: PolicyContextBuilder;
@@ -66,6 +85,13 @@ export type PolicyDecision = GateOutcome | ComputeOutcome;
 
 export type { PolicyEvaluationError } from "./policy-evaluation-error.js";
 
+/**
+ * The full record of one successful evaluation. Beyond the business
+ * {@link decision}, it pins the exact definition that produced it — id, key,
+ * version, payload hash, and engine version — together with the `asOf` instant
+ * the policy was selected for and the wall-clock `evaluatedAt`. That provenance
+ * is what makes a decision reproducible and auditable after the fact.
+ */
 export interface PolicyEvaluationResult {
     readonly decisionId: PolicyDecisionId;
     readonly ref: {
@@ -91,6 +117,18 @@ interface ResolvedPolicyCandidate {
 
 // ─── Service ────────────────────────────────────────────────────────────────
 
+/**
+ * Orchestrates the end-to-end evaluation of a policy: it parses and validates
+ * the context seed, derives the as-of instant, resolves the best matching
+ * definition for the requested key/scope/version, builds the context the policy
+ * needs, and runs it through the right engine (gate or compute).
+ *
+ * The service never throws for an expected failure: every step returns a
+ * {@link Result}, and the failures are folded into a typed
+ * {@link PolicyEvaluationError} so callers branch on `isErr()` rather than
+ * catching. Telemetry is best-effort — a throwing reporter can never abort an
+ * evaluation — which keeps observability strictly side-band.
+ */
 export class PolicyService {
     readonly #reporter: PolicyReporter;
     private readonly catalog: PolicyCatalog;
@@ -136,6 +174,21 @@ export class PolicyService {
         return Result.ok(candidate);
     }
 
+    /**
+     * Evaluates a policy and returns its decision.
+     *
+     * This is the single public entry point. It delegates the actual work to the
+     * private pipeline and wraps it with telemetry: a completed or failed event
+     * is reported either way, but reporting is guarded so it can never change the
+     * outcome. The returned {@link Result} is `ok` with a
+     * {@link PolicyEvaluationResult} on success, or `err` with a typed
+     * {@link PolicyEvaluationError} describing which stage rejected the input —
+     * the method itself does not throw for expected failures.
+     *
+     * @param input - The policy key, scope chain, context version, and seed to
+     *   evaluate, plus the caller's `decisionId`.
+     * @returns A `Result` carrying the decision or the evaluation error.
+     */
     async evaluate(
         input: EvaluateInput,
     ): Promise<Result<PolicyEvaluationResult, PolicyEvaluationError>> {

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 };

package/src/examples/application/in-memory-account-repository.example.ts

@@ -0,0 +1,73 @@
+/**
+ * Reference implementation of a {@link ResultRepository}: shows how a
+ * repository signals recoverable persistence outcomes as `Result` values
+ * instead of throwing.
+ *
+ * - `save` returns a `ConflictError` on an optimistic-concurrency version
+ *   mismatch, otherwise persists and bumps the version.
+ * - `delete` returns a `NotFoundError` when the row is absent.
+ * - `findById` keeps `null` as the "not present" answer (a valid lookup
+ *   result, not an error), still wrapped in a `Result` so genuine infra
+ *   failures could stay in band.
+ *
+ * Consumers import `ResultRepository` from the package root
+ * (`@cullet/erp-core`); the relative paths here keep the example compilable
+ * and test-covered.
+ */
+import type { ResultRepository } from "../../core/application/index.js";
+import {
+    AlreadyExistsError,
+    type ConflictError,
+    NotFoundError,
+} from "../../core/errors/index.js";
+import { Result } from "../../core/result/result.js";
+
+interface Account {
+    readonly id: string;
+    readonly version: number;
+    readonly balance: number;
+}
+
+type AccountError = NotFoundError | ConflictError;
+
+class InMemoryAccountRepository implements ResultRepository<
+    Account,
+    string,
+    AccountError
+> {
+    private readonly store = new Map<string, Account>();
+
+    seed(account: Account): void {
+        this.store.set(account.id, account);
+    }
+
+    async findById(id: string): Promise<Result<Account | null, AccountError>> {
+        return Result.ok(this.store.get(id) ?? null);
+    }
+
+    async save(entity: Account): Promise<Result<void, AccountError>> {
+        const current = this.store.get(entity.id);
+        if (current && current.version !== entity.version) {
+            return Result.err(
+                AlreadyExistsError.detected({
+                    entity: "Account",
+                    operation: "update",
+                    existingId: entity.id,
+                }),
+            );
+        }
+        this.store.set(entity.id, { ...entity, version: entity.version + 1 });
+        return Result.ok(undefined);
+    }
+
+    async delete(id: string): Promise<Result<void, AccountError>> {
+        if (!this.store.has(id)) {
+            return Result.err(new NotFoundError("Account", { id }));
+        }
+        this.store.delete(id);
+        return Result.ok(undefined);
+    }
+}
+
+export { InMemoryAccountRepository };
+export type { Account, AccountError };

package/src/version.ts

@@ -4,4 +4,4 @@
 // Mantemos a versao aqui, dentro de src/, para que a copia full-control seja
 // auto-contida: ao copiar so o conteudo de src/, o entry nao depende de um
 // `../package.json` que deixaria de existir no projeto consumidor.
-export const version = "1.0.10";
+export const version = "1.1.0";