@cullet/erp-core 1.0.9 → 1.0.11

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

@@ -12,6 +12,22 @@ import { assertJsonSafeMetadata } from "./utils/index.js";
 // AppError (abstract base class)
 // ─────────────────────────────────────────────────────────────────────────────
 
+/**
+ * Root of the application/domain error hierarchy. Every error the system raises
+ * on purpose extends `AppError`, which gives callers a single `instanceof` to
+ * catch and a uniform, serializable shape to log and transport.
+ *
+ * Beyond the native `Error` message it carries a stable `code` (the contract the
+ * outside world matches on), an optional non-leaking `publicMessage`, a
+ * severity, JSON-safe `metadata`, and the correlation/request/command ids that
+ * stitch an error back to the request that produced it. The metadata is
+ * validated as JSON-safe on construction, so a logger can serialize any
+ * `AppError` without hitting a circular reference or a non-serializable value.
+ *
+ * Abstract on purpose: callers should throw a specific subclass (e.g.
+ * {@link ValidationError}, {@link NotFoundError}) so the `code` and shape are
+ * meaningful, never a bare `AppError`.
+ */
 abstract class AppError extends Error {
     public readonly code: string;
     public readonly cause?: unknown;
@@ -36,6 +52,23 @@ abstract class AppError extends Error {
      */
     public readonly commandId?: string;
 
+    /**
+     * Builds the common error envelope shared by every subclass.
+     *
+     * `name` is taken from `new.target` so the thrown instance reports its
+     * concrete subclass name (not `"AppError"`), and the prototype is re-pinned
+     * via `setPrototypeOf` so `instanceof` keeps working after transpilation to
+     * older targets where extending built-ins breaks the chain. `createdAtIso`
+     * defaults to now, and `metadata` is validated as JSON-safe so the error is
+     * always serializable.
+     *
+     * Declared `protected`: instantiate a concrete subclass, never `AppError`.
+     *
+     * @param message - The internal, developer-facing message.
+     * @param code - The stable machine-readable code callers match on.
+     * @param options - Optional cause, metadata, severity, and correlation ids.
+     * @throws When `options.metadata` contains a value that is not JSON-safe.
+     */
     protected constructor(
         message: string,
         code: string,

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

@@ -61,6 +61,19 @@ type AuthorizationErrorFactoryOptions = Omit<
 // AuthorizationError
 // ─────────────────────────────────────────────────────────────────────────────
 
+/**
+ * Raised when an authenticated actor is not allowed to perform a business
+ * action — the "you may not" error, distinct from authentication ("who are
+ * you"). Maps to an HTTP 403 at the edge.
+ *
+ * The discriminating {@link reason} records *why* access was denied (a flat
+ * forbid, a missing role/capability, an out-of-scope target, or a policy
+ * decision) so the boundary can shape the response without re-deriving it. The
+ * metadata is deliberately built around a stable business `action` and a
+ * type/id resource reference rather than an HTTP route or full payload, keeping
+ * sensitive data out of logs. Instances are frozen. Construct through the
+ * static factories, never directly.
+ */
 class AuthorizationError extends AppError {
     public readonly reason: AuthorizationErrorReason;
 
@@ -98,6 +111,12 @@ class AuthorizationError extends AppError {
     // Factories
     // ─────────────────────────────────────────────────────────────────────────
 
+    /**
+     * A flat denial with no more specific reason — the actor simply may not
+     * perform this action. Reach for a more precise factory
+     * ({@link AuthorizationError.missingCapability}, {@link AuthorizationError.outOfScope},
+     * {@link AuthorizationError.policyDenied}) when the cause is known.
+     */
     static forbidden(
         input: AuthorizationErrorFactoryOptions,
     ): AuthorizationError {
@@ -110,6 +129,15 @@ class AuthorizationError extends AppError {
         });
     }
 
+    /**
+     * The action was denied by an evaluated policy. Captures the deciding
+     * policy's id, version, and evaluation instant into the metadata (with
+     * `decision: "deny"`) so the denial is auditable back to the exact policy
+     * that produced it.
+     *
+     * @param input - Factory options plus the required `policyId`,
+     *   `policyVersion`, and `evaluatedAtIso` of the deciding policy.
+     */
     static policyDenied(
         input: AuthorizationErrorFactoryOptions & {
             policyId: string;
@@ -130,6 +158,13 @@ class AuthorizationError extends AppError {
         });
     }
 
+    /**
+     * The actor lacks a required role or capability. The expected
+     * {@link AuthorizationRequirement} is recorded so the boundary can tell the
+     * caller precisely what grant is missing.
+     *
+     * @param input - Factory options plus the `required` role/capability/scope.
+     */
     static missingCapability(
         input: AuthorizationErrorFactoryOptions & {
             required: AuthorizationRequirement;
@@ -147,6 +182,14 @@ class AuthorizationError extends AppError {
         });
     }
 
+    /**
+     * The actor may perform the action in general, but not on *this* target —
+     * the resource falls outside the actor's permitted scope (e.g. a different
+     * school or tenant than the one they are bound to).
+     *
+     * @param input - Factory options plus the optional `required` scope that the
+     *   target failed to satisfy.
+     */
     static outOfScope(
         input: AuthorizationErrorFactoryOptions & {
             required?: AuthorizationRequirement;

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

@@ -26,6 +26,11 @@ type ConflictErrorMetadata = {
     hint?: string;
 };
 
+/**
+ * Storage-level description of a unique-constraint breach, as reported by a
+ * database driver. Used to translate a raw DB error into a domain
+ * {@link DuplicateError} via {@link translateUniqueViolationToDuplicate}.
+ */
 type UniqueConstraintViolation = {
     kind: "unique_violation";
     constraintName?: string;
@@ -33,6 +38,17 @@ type UniqueConstraintViolation = {
     columns?: string[];
 };
 
+/**
+ * Base for errors that signal a state conflict — the request collides with data
+ * that already exists. Common at an HTTP 409 boundary.
+ *
+ * The discriminating {@link kind} lets a handler branch on *why* it conflicted
+ * (an already-existing record, a domain duplicate, or a raw storage uniqueness
+ * breach) without `instanceof` chains. Abstract: construct one of the concrete
+ * subclasses through its `detected(...)` factory, which fills in the right code,
+ * message, and metadata. Instances are frozen, so a conflict error can be shared
+ * and rethrown without risk of tampering.
+ */
 abstract class ConflictError extends AppError {
     public readonly kind: ConflictKind;
 
@@ -58,6 +74,11 @@ abstract class ConflictError extends AppError {
     }
 }
 
+/**
+ * The operation cannot proceed because a matching record already exists —
+ * e.g. creating something whose natural key is already taken. Construct via
+ * {@link AlreadyExistsError.detected}.
+ */
 class AlreadyExistsError extends ConflictError {
     private constructor(
         input: {
@@ -74,6 +95,14 @@ class AlreadyExistsError extends ConflictError {
         });
     }
 
+    /**
+     * Builds an {@link AlreadyExistsError} for a detected collision. `operation`
+     * defaults to `"create"` and a generic retry `hint` is supplied when none is
+     * given, so the error is actionable even from a minimal call site.
+     *
+     * @param input - The conflicting entity plus optional non-sensitive context
+     *   (operation, field, existing id, value hash/preview, correlation ids).
+     */
     static detected(input: {
         entity: string;
         operation?: string;
@@ -107,6 +136,13 @@ class AlreadyExistsError extends ConflictError {
     }
 }
 
+/**
+ * A domain-level duplicate: the data being written would duplicate an existing
+ * record under the model's own uniqueness rules. Use this when the duplication
+ * is recognized in the domain, as opposed to a raw DB constraint
+ * ({@link UniqueConstraintViolationError}). Construct via
+ * {@link DuplicateError.detected}.
+ */
 class DuplicateError extends ConflictError {
     private constructor(
         input: {
@@ -122,6 +158,13 @@ class DuplicateError extends ConflictError {
         });
     }
 
+    /**
+     * Builds a {@link DuplicateError} for a detected duplicate, defaulting to a
+     * "adjust the data so it does not duplicate" hint when none is provided.
+     *
+     * @param input - The conflicting entity plus optional non-sensitive context
+     *   (field, constraint name, existing id, value hash/preview, correlation ids).
+     */
     static detected(input: {
         entity: string;
         operation?: string;
@@ -159,6 +202,14 @@ class DuplicateError extends ConflictError {
     }
 }
 
+/**
+ * A uniqueness breach surfaced by the storage layer itself (a database unique
+ * index), carrying the raw {@link UniqueConstraintViolation} (constraint, table,
+ * columns). Keep this distinct from {@link DuplicateError}: this one is the
+ * infrastructure signal; translate it into a domain duplicate at the boundary
+ * with {@link translateUniqueViolationToDuplicate} when the model should own the
+ * message. Construct via {@link UniqueConstraintViolationError.detected}.
+ */
 class UniqueConstraintViolationError extends ConflictError {
     private constructor(
         input: {
@@ -176,6 +227,13 @@ class UniqueConstraintViolationError extends ConflictError {
         });
     }
 
+    /**
+     * Builds a {@link UniqueConstraintViolationError} from the constraint details
+     * a driver reports, packaging them into a nested `violation` payload.
+     *
+     * @param input - The entity plus the offending constraint name, table, and
+     *   columns, and optional correlation ids.
+     */
     static detected(input: {
         entity: string;
         operation?: string;
@@ -210,6 +268,17 @@ class UniqueConstraintViolationError extends ConflictError {
     }
 }
 
+/**
+ * Translates a raw storage {@link UniqueConstraintViolation} into a domain-level
+ * {@link DuplicateError}. This is the seam where an infrastructure concern (a DB
+ * unique index firing) is re-expressed in the language of the model, so callers
+ * upstream catch a `DuplicateError` and never have to know a database was
+ * involved.
+ *
+ * @param input - The entity, the driver-reported `violation`, and optional
+ *   request context (`ctx`) carrying correlation ids and a clock instant.
+ * @returns A {@link DuplicateError} carrying the constraint name as its field hint.
+ */
 function translateUniqueViolationToDuplicate(input: {
     entity: string;
     operation?: string;

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

@@ -42,6 +42,18 @@ type IntegrationErrorConstructorParams = {
     metadata: IntegrationErrorMetadata;
 } & IntegrationErrorAppOptions;
 
+/**
+ * Raised when a call to an external provider fails — a timeout, an unreachable
+ * endpoint, or a malformed response. This is the boundary error that separates
+ * "our code is fine, the outside world misbehaved" from internal faults, which
+ * matters for retry and alerting decisions.
+ *
+ * Every instance records the `provider`, the `operation`, and timing
+ * (`startedAtIso` / `durationMs`) so failures are correlatable across services
+ * and a slow dependency is visible in the metadata. The discriminating
+ * {@link reason} lets callers decide whether a failure is worth retrying.
+ * Instances are frozen; construct through the static factories.
+ */
 class IntegrationError extends AppError {
     public readonly reason: IntegrationErrorReason;
 
@@ -56,6 +68,10 @@ class IntegrationError extends AppError {
         Object.freeze(this);
     }
 
+    /**
+     * The provider did not respond within the allotted time. Usually retryable,
+     * since a timeout leaves the outcome unknown rather than known-failed.
+     */
     static timeout(options: IntegrationErrorTimeoutOptions): IntegrationError {
         return new IntegrationError({
             message: "Timeout while integrating with external provider",
@@ -66,6 +82,10 @@ class IntegrationError extends AppError {
         });
     }
 
+    /**
+     * The provider could not be reached at all (connection refused, DNS
+     * failure, network partition) — the request never landed.
+     */
     static unreachable(
         options: IntegrationErrorEndpointOptions,
     ): IntegrationError {
@@ -78,6 +98,11 @@ class IntegrationError extends AppError {
         });
     }
 
+    /**
+     * The provider answered, but with something the system cannot use — an
+     * unexpected status, an unparsable body, or a contract mismatch. Unlike a
+     * timeout this is a definite failure, so blind retries rarely help.
+     */
     static badResponse(
         options: IntegrationErrorEndpointOptions,
     ): IntegrationError {

package/src/core/errors/not-found-error.ts

@@ -6,7 +6,21 @@ import type { AppErrorOptions } from "./types.js";
 // NotFoundError
 // ─────────────────────────────────────────────────────────────────────────────
 
+/**
+ * Raised when a requested resource does not exist. Maps naturally onto an HTTP
+ * 404 at the edge, but stays transport-agnostic here.
+ *
+ * The `resource` name builds the message (`"<resource> not found"`) and, with
+ * the optional lookup `criteria`, lands in the metadata so logs show *what* was
+ * searched for without the caller having to restate it in the message.
+ */
 class NotFoundError extends AppError {
+    /**
+     * @param resource - Human-readable name of the missing resource (e.g. `"Order"`).
+     * @param criteria - Optional lookup keys used in the search; recorded in
+     *   metadata to aid debugging. Avoid putting sensitive values here.
+     * @param options - Optional cause, correlation ids, and extra metadata.
+     */
     constructor(
         resource: string,
         criteria?: Record<string, unknown>,

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/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/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.9";
+export const version = "1.0.11";