@cullet/erp-core 1.4.0 → 2.0.0

package/dist/version.d.ts

@@ -1,9 +1,36 @@
 //#region src/core/versioning/version.d.ts
+/**
+ * A structural contract version in `MAJOR.MINOR` form (e.g. `"1.0"`, `"2.5"`).
+ *
+ * The template-literal type is intentionally loose — it also accepts strings
+ * the module rejects at runtime (e.g. `"1.0.0"` matches as `1` · `.` · `0.0`).
+ * The runtime regex in {@link version} is the real guard; the type is only a
+ * light hint.
+ */
 type ContractVersion = `${number}.${number}`;
+/** Anything a class decorator can stamp a static property onto. */
 type VersionedTarget = {
   readonly prototype: object;
 };
 declare const CONTRACT_VERSION_PROPERTY: "CONTRACT_VERSION";
+/**
+ * Class decorator that stamps a `MAJOR.MINOR` structural contract version onto
+ * the class as a static `CONTRACT_VERSION` property.
+ *
+ * The property is defined **non-writable, non-configurable and non-enumerable**
+ * on purpose: it must not be reassigned or redefined (tampering with a contract
+ * version silently corrupts migration decisions), and keeping it off enumeration
+ * excludes it from `JSON.stringify`/`for..in`. A consequence of
+ * `configurable: false` is that decorating the same class twice throws
+ * `TypeError: Cannot redefine property` — a deliberate fail-fast.
+ *
+ * Note on inheritance: a subclass that is not re-decorated inherits its base's
+ * `CONTRACT_VERSION` through the static prototype chain. Re-decorate any
+ * subclass whose persisted shape diverges from its base.
+ *
+ * @throws {InvariantViolationException} When `contractVersion` is not
+ *   `MAJOR.MINOR` (validated at module-load time, when the decorator runs).
+ */
 declare function version<const TVersion extends ContractVersion>(contractVersion: TVersion): (target: VersionedTarget) => void;
 //#endregion
 export { version as i, ContractVersion as n, VersionedTarget as r, CONTRACT_VERSION_PROPERTY as t };

package/dist/versioning/index.d.cts

@@ -1,3 +1,3 @@
 import { i as version, n as ContractVersion, r as VersionedTarget, t as CONTRACT_VERSION_PROPERTY } from "../version.cjs";
-import { a as buildDomainEventContractVersions, i as DomainEventEnvelope, n as DomainEventContractSelection, o as createDomainEventEnvelope, r as DomainEventContractVersions, t as CreateDomainEventEnvelopeInput } from "../domain-event-contracts.cjs";
-export { CONTRACT_VERSION_PROPERTY, ContractVersion, CreateDomainEventEnvelopeInput, DomainEventContractSelection, DomainEventContractVersions, DomainEventEnvelope, VersionedTarget, buildDomainEventContractVersions, createDomainEventEnvelope, version };
+import { a as DomainEventEnvelope, i as DomainEventContractVersions, n as CreateDomainEventEnvelopeInput, o as buildDomainEventContractVersions, r as DomainEventContractSelection, s as createDomainEventEnvelope, t as ContractVersioned } from "../domain-event-contracts.cjs";
+export { CONTRACT_VERSION_PROPERTY, ContractVersion, ContractVersioned, CreateDomainEventEnvelopeInput, DomainEventContractSelection, DomainEventContractVersions, DomainEventEnvelope, VersionedTarget, buildDomainEventContractVersions, createDomainEventEnvelope, version };

package/dist/versioning/index.d.ts

@@ -1,3 +1,3 @@
 import { i as version, n as ContractVersion, r as VersionedTarget, t as CONTRACT_VERSION_PROPERTY } from "../version.js";
-import { a as buildDomainEventContractVersions, i as DomainEventEnvelope, n as DomainEventContractSelection, o as createDomainEventEnvelope, r as DomainEventContractVersions, t as CreateDomainEventEnvelopeInput } from "../domain-event-contracts.js";
-export { CONTRACT_VERSION_PROPERTY, ContractVersion, CreateDomainEventEnvelopeInput, DomainEventContractSelection, DomainEventContractVersions, DomainEventEnvelope, VersionedTarget, buildDomainEventContractVersions, createDomainEventEnvelope, version };
+import { a as DomainEventEnvelope, i as DomainEventContractVersions, n as CreateDomainEventEnvelopeInput, o as buildDomainEventContractVersions, r as DomainEventContractSelection, s as createDomainEventEnvelope, t as ContractVersioned } from "../domain-event-contracts.js";
+export { CONTRACT_VERSION_PROPERTY, ContractVersion, ContractVersioned, CreateDomainEventEnvelopeInput, DomainEventContractSelection, DomainEventContractVersions, DomainEventEnvelope, VersionedTarget, buildDomainEventContractVersions, createDomainEventEnvelope, version };

package/meta.json

@@ -1,7 +1,7 @@
 {
     "schemaVersion": "2",
     "name": "erp-core",
-    "version": "1.4.0",
+    "version": "2.0.0",
     "description": "Núcleo arquitetural para ERP em TypeScript — entidades, value objects, erros tipados e policies declaráveis sobre clean architecture.",
     "compatibility": {
         "engines": {
@@ -83,6 +83,7 @@
         "PermissionSet",
         "RbacAuthorizer",
         "AuthorizerPort",
+        "rbacContextFields",
         "AbacRule",
         "AbacPolicySet",
         "AbacAuthorizer",
@@ -105,7 +106,9 @@
         "1.1.0 - **New: `ResultRepository`, `UseCaseObservability`, and `./application` subpath**",
         "1.2.0 - Add zod-free subpaths for the stable core primitives and a value-object equality plugin system.",
         "1.3.0 - Add zod-free subpaths for the stable core primitives and a value-object equality plugin system.",
-        "1.4.0 - Add a zod-free ABAC module and the `./abac` subpath."
+        "1.4.0 - Add a zod-free ABAC module and the `./abac` subpath.",
+        "1.5.0 - Add a zod-free ABAC module and the `./abac` subpath.",
+        "2.0.0 - Harden RBAC/ABAC, the policy condition engine, bitemporal primitives, the Result/Outcome module and the domain-exception hierarchy, plus fix several invariant bugs found while doing so."
     ],
     "deprecated": false
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cullet/erp-core",
-    "version": "1.4.0",
+    "version": "2.0.0",
     "description": "Núcleo arquitetural para ERP em TypeScript — entidades, value objects, erros tipados e policies declaráveis sobre clean architecture.",
     "type": "module",
     "repository": {

package/src/core/abac/authorizer.ts

@@ -7,7 +7,7 @@ import type { AbacRequest } from "./abac-request.js";
 import { abacContext } from "./attributes.js";
 import { combine, type CombiningAlgorithm } from "./combining.js";
 import type { AbacPolicySet } from "./domain/policy-set.js";
-import type { AbacRule } from "./domain/rule.js";
+import type { AbacRule, RuleEffect } from "./domain/rule.js";
 
 // ABAC reuses the gate engine's v1 condition matcher; the version stamps the
 // evaluation reports the shared reporter emits.
@@ -34,16 +34,30 @@ interface AbacDecision {
  * "errors as values" contract of `RbacAuthorizer`/`GateEngineV1`.
  *
  * A denial maps to {@link AuthorizationError.policyDenied}, attributed to the
- * deciding rule's `id`/`version`; a condition-evaluation failure (a missing
+ * deciding rule's `id`/`version`. A condition-evaluation failure (a missing
  * attribute, a wrong-typed operand) fails closed as
- * {@link AuthorizationError.forbidden}. Loading the dynamic attributes is the
- * consumer's job (behind an `AbacAuthorizerPort` adapter); this class only decides.
+ * {@link AuthorizationError.forbidden} — also attributed to the culprit rule's
+ * `id`/`version` — unless the set opts into `onEvaluationError: "skip-rule"`, in
+ * which case the unevaluable rule is skipped and the rest decide. Every resolved
+ * decision (PERMIT and DENY) is emitted best-effort through the configured
+ * reporter as an `abac-decision` event (silent by default). Timestamps come from
+ * an injectable `clock` (default `() => new Date()`), so the decisor is pure
+ * given one. Loading the dynamic attributes is the consumer's job (behind an
+ * `AbacAuthorizerPort` adapter); this class only decides.
  */
 class AbacAuthorizer {
     private readonly coreConfig: CoreConfig;
+    private readonly clock: () => Date;
 
-    constructor(params: { readonly coreConfig?: CoreConfig } = {}) {
+    constructor(
+        params: {
+            readonly coreConfig?: CoreConfig;
+            /** Injectable clock for deterministic timestamps; defaults to `() => new Date()`. */
+            readonly clock?: () => Date;
+        } = {},
+    ) {
         this.coreConfig = params.coreConfig ?? coreConfig;
+        this.clock = params.clock ?? (() => new Date());
     }
 
     authorize(
@@ -60,12 +74,22 @@ class AbacAuthorizer {
         for (const rule of policies.rules) {
             const matched = evaluator.evaluate(rule.condition);
             if (matched.isErr()) {
-                // Fail closed: a technical evaluation error is never a silent PERMIT.
+                if (policies.onEvaluationError === "skip-rule") {
+                    // Escape valve for evolving rules: drop the unevaluable rule
+                    // (the evaluator already reported the anomaly) and let the
+                    // rest decide, instead of failing the whole set closed.
+                    continue;
+                }
+                // Fail closed: a technical evaluation error is never a silent
+                // PERMIT. Attribute the deny to the culprit rule so the 403 is
+                // triageable without turning on the reporter.
                 return Result.err(
                     AuthorizationError.forbidden({
                         action: request.action,
                         resource: request.resource,
-                        actor: { userId: request.actor.raw },
+                        actor: { actorId: request.actor.raw },
+                        policyId: rule.id,
+                        policyVersion: rule.version,
                         details: matched.errorOrNull() ?? undefined,
                     }),
                 );
@@ -81,13 +105,15 @@ class AbacAuthorizer {
             policies.defaultEffect,
         );
 
+        this.reportDecision(request, policies, effect, decidingRule);
+
         if (effect === "PERMIT") {
             return Result.ok({
                 action: request.action,
                 effect: "PERMIT",
                 matchedRule: decidingRule?.id ?? "<default>",
                 algorithm: policies.algorithm,
-                grantedAtIso: new Date().toISOString(),
+                grantedAtIso: this.clock().toISOString(),
             });
         }
 
@@ -95,14 +121,38 @@ class AbacAuthorizer {
             AuthorizationError.policyDenied({
                 policyId: decidingRule?.id ?? "<default-deny>",
                 policyVersion: decidingRule?.version ?? 0,
-                evaluatedAtIso: new Date().toISOString(),
+                evaluatedAtIso: this.clock().toISOString(),
                 action: request.action,
                 resource: request.resource,
-                actor: { userId: request.actor.raw },
+                actor: { actorId: request.actor.raw },
                 reasonCode: decidingRule?.id,
             }),
         );
     }
+
+    // Best-effort audit trail: emits the resolved decision (PERMIT and DENY)
+    // through the configured reporter, silent by default.
+    private reportDecision(
+        request: AbacRequest,
+        policies: AbacPolicySet,
+        effect: RuleEffect,
+        decidingRule: AbacRule | undefined,
+    ): void {
+        this.coreConfig.reportSafely({
+            kind: "abac-decision",
+            level: "info",
+            action: request.action,
+            resource: request.resource,
+            actorId: request.actor.raw,
+            effect,
+            decidingRuleId:
+                decidingRule?.id ??
+                (effect === "PERMIT" ? "<default>" : "<default-deny>"),
+            decidingRuleVersion: decidingRule?.version,
+            algorithm: policies.algorithm,
+            occurredAt: this.clock(),
+        });
+    }
 }
 
 export { AbacAuthorizer, type AbacDecision };

package/src/core/abac/domain/policy-set.ts

@@ -1,41 +1,84 @@
+import { ValidationCode } from "../../exceptions/validation-code.js";
+import { InvalidValueException } from "../../exceptions/validation-exception.js";
+import { ValidationField } from "../../exceptions/validation-field.js";
 import type { CombiningAlgorithm } from "../combining.js";
 
 import type { AbacRule, RuleEffect } from "./rule.js";
 
+/**
+ * How the {@link AbacAuthorizer} reacts when a rule's condition cannot be
+ * evaluated (a referenced attribute is absent, an operand is wrong-typed).
+ *
+ * - `fail-closed` (default, secure): the whole decision fails closed as
+ *   `forbidden`. Safe, but it means adding a rule that reads an attribute a call
+ *   site does not populate makes that call site deny everything until it does.
+ * - `skip-rule`: the unevaluable rule is dropped from the applicable set and the
+ *   remaining rules decide — the escape valve for evolving rules without
+ *   trailing every call site. The evaluator still reports the anomaly.
+ */
+export type OnEvaluationError = "fail-closed" | "skip-rule";
+
+const POLICY_SET_FIELD = ValidationField.of("abacPolicySet");
+
 /**
  * An ordered collection of {@link AbacRule}s plus how to combine them
- * ({@link CombiningAlgorithm}) and what to decide when no rule applies
- * ({@link defaultEffect}). This is where ABAC goes beyond a single gate
+ * ({@link CombiningAlgorithm}), what to decide when no rule applies
+ * ({@link defaultEffect}), and how to react to an unevaluable rule
+ * ({@link onEvaluationError}). This is where ABAC goes beyond a single gate
  * condition: several PERMIT/DENY rules resolved by an explicit algorithm.
  *
- * Closed by default — the combining algorithm defaults to `"deny-overrides"` and
- * the default effect to `"DENY"`, so a request matching nothing is denied. A
- * plain holder (not a value object); build through {@link of}.
+ * Closed by default — the combining algorithm defaults to `"deny-overrides"`,
+ * the default effect to `"DENY"`, and evaluation errors to `"fail-closed"`, so a
+ * request matching nothing (or hitting a technical error) is denied. A plain
+ * holder (not a value object); build through {@link of}.
  */
 class AbacPolicySet {
     private constructor(
         private readonly _rules: readonly AbacRule[],
         private readonly _algorithm: CombiningAlgorithm,
         private readonly _defaultEffect: RuleEffect,
+        private readonly _onEvaluationError: OnEvaluationError,
     ) {
         Object.freeze(this._rules);
         Object.freeze(this);
     }
 
+    /**
+     * Builds a policy set. Rejects duplicate rule ids with
+     * {@link InvalidValueException} so a denial's `policyId` attribution is
+     * unambiguous.
+     */
     static of(
         rules: readonly AbacRule[],
         options: {
             readonly algorithm?: CombiningAlgorithm;
             readonly defaultEffect?: RuleEffect;
+            readonly onEvaluationError?: OnEvaluationError;
         } = {},
     ): AbacPolicySet {
+        AbacPolicySet.assertUniqueIds(rules);
         return new AbacPolicySet(
             [...rules],
             options.algorithm ?? "deny-overrides",
             options.defaultEffect ?? "DENY",
+            options.onEvaluationError ?? "fail-closed",
         );
     }
 
+    private static assertUniqueIds(rules: readonly AbacRule[]): void {
+        const seen = new Set<string>();
+        for (const rule of rules) {
+            if (seen.has(rule.id)) {
+                throw new InvalidValueException(
+                    POLICY_SET_FIELD.nested("rules"),
+                    ValidationCode.ALREADY_EXISTS,
+                    `abac policy set has duplicate rule id "${rule.id}"; ids must be unique for unambiguous audit attribution`,
+                );
+            }
+            seen.add(rule.id);
+        }
+    }
+
     get rules(): readonly AbacRule[] {
         return this._rules;
     }
@@ -47,6 +90,10 @@ class AbacPolicySet {
     get defaultEffect(): RuleEffect {
         return this._defaultEffect;
     }
+
+    get onEvaluationError(): OnEvaluationError {
+        return this._onEvaluationError;
+    }
 }
 
 export { AbacPolicySet };

package/src/core/abac/domain/rule.ts

@@ -2,9 +2,10 @@ import { ValidationCode } from "../../exceptions/validation-code.js";
 import { InvalidValueException } from "../../exceptions/validation-exception.js";
 import { ValidationField } from "../../exceptions/validation-field.js";
 import { ValueObject } from "../../domain/value-object.js";
-import type {
-    ConditionNode,
-    ConditionOp,
+import {
+    CONDITION_OPS,
+    type ConditionNode,
+    type ConditionOp,
 } from "../../policies/engines/v1/condition-types.js";
 
 /** Whether a matching {@link AbacRule} permits or denies the action. */
@@ -26,18 +27,9 @@ type AbacRuleProps = {
 
 const RULE_FIELD = ValidationField.of("abacRule");
 
-const CONDITION_OPS = new Set<ConditionOp>([
-    "eq",
-    "neq",
-    "gt",
-    "gte",
-    "lt",
-    "lte",
-    "in",
-    "notIn",
-    "isNull",
-    "isNotNull",
-]);
+// Derived from the evaluator's own operator list (single source of truth) so a
+// new operator becomes usable in ABAC rules without a parallel edit here.
+const SUPPORTED_OPS = new Set<ConditionOp>(CONDITION_OPS);
 
 const RULE_EFFECTS = new Set<RuleEffect>(["PERMIT", "DENY"]);
 
@@ -57,6 +49,26 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
  * authored in TypeScript — trusted data, not untrusted JSON — the structural
  * check is a hand-rolled walk of the condition tree rather than a schema parse.
  * Build one through {@link of}; the constructor is private.
+ *
+ * **Attribute semantics a rule author must know (the condition is evaluated by
+ * the shared gate/compute engine, whose runtime rules apply here too):**
+ * - **A referenced attribute that is *absent* from the request is a technical
+ *   evaluation error, not a non-match.** By default (`onEvaluationError:
+ *   "fail-closed"` on the {@link AbacPolicySet}) that error fails the *entire*
+ *   decision closed — so adding a rule that reads an attribute a given call site
+ *   does not yet populate makes that call site start returning `forbidden`,
+ *   *even for requests the older rules used to permit*. Choose
+ *   `onEvaluationError: "skip-rule"` on the set to skip an unevaluable rule
+ *   instead of failing the whole set.
+ * - **`isNull` / `isNotNull` test for an explicit `null`/`undefined` *value*, not
+ *   for a missing key.** A key that is absent from the bag never reaches the
+ *   operator — it short-circuits to the missing-attribute error above. To match
+ *   "no deletedAt", the consumer must put `deletedAt: null` in the bag, not omit
+ *   it. Pass `allowNull: true` on a relational leaf to treat a present `null` as
+ *   a non-match instead of an error.
+ * - **Date comparison operands must be strict ISO-8601 UTC**
+ *   (`YYYY-MM-DDTHH:mm:ss.sssZ`); a bare `"2026-07-09"` or an offset like
+ *   `+00:00` is rejected as an invalid operand and fails closed.
  */
 class AbacRule extends ValueObject<AbacRuleProps, AbacRuleProps> {
     private constructor(props: AbacRuleProps) {
@@ -138,7 +150,7 @@ class AbacRule extends ValueObject<AbacRuleProps, AbacRuleProps> {
             }
             if (
                 typeof node.op !== "string" ||
-                !CONDITION_OPS.has(node.op as ConditionOp)
+                !SUPPORTED_OPS.has(node.op as ConditionOp)
             ) {
                 AbacRule.rejectCondition(
                     `abac rule condition leaf "op" is not a supported operator, got "${String(node.op)}"`,

package/src/core/abac/index.ts

@@ -2,6 +2,12 @@
 // combining algorithms, the attribute→context flattening, the pure decisor, the
 // optional RBAC+ABAC composite, and the AbacAuthorizerPort seam (which physically
 // lives under application/ports/ but is surfaced here as the ABAC public home).
+//
+// Rule-author footguns (documented in full on AbacRule): a referenced attribute
+// absent from the request is a technical error that, by default, fails the whole
+// decision closed — set `onEvaluationError: "skip-rule"` on the AbacPolicySet to
+// skip the unevaluable rule instead. `isNull`/`isNotNull` match an explicit
+// `null` value, never a missing key.
 
 export type { AbacAuthorizerPort } from "../application/ports/abac-authorizer.port.js";
 
@@ -13,7 +19,7 @@ export {
     type CompositeAccessRequest,
     CompositeAuthorizer,
 } from "./composite-authorizer.js";
-export { AbacPolicySet } from "./domain/policy-set.js";
+export { AbacPolicySet, type OnEvaluationError } from "./domain/policy-set.js";
 export {
     AbacRule,
     type AbacRuleProps,

package/src/core/application/commands/command.ts

@@ -1,5 +1,6 @@
 import { UseCase } from "../use-case.js";
 import { version } from "../../versioning/version.js";
+import type { TraceAttributeValue } from "../ports/tracer.port.js";
 import type { Result } from "../../result/result.js";
 
 import { RequestedBy } from "./requested-by.js";
@@ -22,7 +23,19 @@ interface CommandInput {
 abstract class Command<
     Input extends CommandInput,
     Output extends Result<unknown, unknown> = Result<void, never>,
-> extends UseCase<Input, Output> {}
+> extends UseCase<Input, Output> {
+    /**
+     * Surfaces the actor's *kind* (`"user"` / `"system"`) on the span and
+     * metrics so a write can be sliced by origin. Only the low-cardinality
+     * `kind` is emitted — never the raw id, which would blow up label
+     * cardinality and could leak a user identifier into metrics.
+     */
+    protected override spanAttributes(
+        input: Input,
+    ): Readonly<Record<string, TraceAttributeValue>> {
+        return { "requested_by.kind": input.requestedBy.kind };
+    }
+}
 
 export type { CommandInput };
 export { Command };

package/src/core/application/commands/requested-by.ts

@@ -1,10 +1,15 @@
 import { ValidationCode } from "../../exceptions/validation-code.js";
 import { InvalidValueException } from "../../exceptions/validation-exception.js";
 import { ValidationField } from "../../exceptions/validation-field.js";
+import { UUID_PATTERN } from "../../shared/uuid.js";
 
 // Identifies who triggered a Command.
 // Two valid formats:
-//   - Human user: UUID v4 (e.g.: "550e8400-e29b-41d4-a716-446655440000")
+//   - Human user: canonical RFC-4122 UUID, versions 1–8 (including the
+//     time-ordered v7) — the same pattern `UuidIdentifier` enforces
+//     (e.g.: "550e8400-e29b-41d4-a716-446655440000"). The constraint is
+//     single-sourced in `shared/uuid.ts`, so `UuidIdentifier` and this value
+//     always accept the same set of versions.
 //   - System identity: "system:<job>" where <job> is [a-z][a-z0-9]*(-[a-z0-9]+)*
 //     (e.g.: "system:late-fee-job", "system:email-sender")
 //
@@ -15,9 +20,6 @@ type RequestedByKind = "user" | "system";
 
 const REQUESTED_BY_FIELD = ValidationField.of("requestedBy");
 
-const UUID_PATTERN =
-    /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-
 // system:<job> where <job> starts with a lowercase letter and may have hyphens between segments
 const SYSTEM_IDENTITY_PATTERN = /^system:[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
 
@@ -27,7 +29,13 @@ class RequestedBy {
 
     private constructor(kind: RequestedByKind, raw: string) {
         this.kind = kind;
-        this.raw = raw;
+        // UUIDs are matched case-insensitively (see `shared/uuid.ts`), so the
+        // same user id can arrive lowercased from Postgres and uppercased from a
+        // JWT. Canonicalize user ids to lowercase here — the single choke point
+        // every factory passes through — so exact-string comparators downstream
+        // (`Grant.appliesTo`, `rbacContextFields`) never miss the right identity
+        // on case alone. System identities are already lowercase by pattern.
+        this.raw = kind === "user" ? raw.toLowerCase() : raw;
         Object.freeze(this);
     }
 

package/src/core/application/index.ts

@@ -15,6 +15,7 @@ export type {
     PolicyPortError,
     Repository,
     ResultRepository,
+    ResultTemporalRepository,
     TraceAttributeValue,
     TraceSpan,
     TracerPort,
@@ -22,7 +23,7 @@ export type {
     TemporalRepository,
 } from "./ports/index.js";
 export { mapPolicyEvaluationError } from "./policy-error-mapper.js";
-export type { CacheStrategy, Page } from "./queries/index.js";
+export type { CacheStrategy, Page, QueryOutput } from "./queries/index.js";
 export { Query } from "./queries/index.js";
 export {
     assertTemporalContext,

package/src/core/application/policy-error-mapper.ts

@@ -49,7 +49,13 @@ export function mapPolicyEvaluationError(err: PolicyEvaluationError): AppError {
                 { cause: err.cause },
             );
         case "ENGINE_FAILURE":
+            // `engine`/`engineVersion` are internal detail kept in `metadata`
+            // for logs. `publicMessage` gives the HTTP boundary a safe string
+            // to expose so it never has to serialize this metadata to a client
+            // on a 500. (Whether the boundary leaks `metadata` is still its
+            // call — this only hands it the non-leaking alternative.)
             return new UnexpectedError(err.message, err.cause, {
+                publicMessage: "Policy evaluation failed unexpectedly.",
                 metadata: {
                     policyKey: err.policyKey,
                     engine: err.engine,

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

@@ -8,6 +8,7 @@ export type {
 } from "./policy-port.js";
 export type { Repository, ResultRepository } from "./repository.port.js";
 export type {
+    ResultTemporalRepository,
     TemporalHistory,
     TemporalRepository,
 } from "./temporal-repository.port.js";
@@ -16,3 +17,9 @@ export type {
     TraceSpan,
     TracerPort,
 } from "./tracer.port.js";
+
+// Note: `AuthorizerPort` (RBAC) and `AbacAuthorizerPort` (ABAC) also live in
+// this folder but are intentionally NOT re-exported here — they belong to the
+// `rbac` / `abac` surfaces and are exported from those barrels instead (each
+// port file documents why). Import them from `cullet/erp-core` rbac/abac
+// entry points, not from this ports barrel.

package/src/core/application/ports/temporal-repository.port.ts

@@ -1,9 +1,21 @@
 import type { TemporalSnapshot } from "../../domain/temporal/index.js";
+import type { AppError } from "../../errors/index.js";
+import type { Result } from "../../result/result.js";
 
-import type { Repository } from "./repository.port.js";
+import type { Repository, ResultRepository } from "./repository.port.js";
 
 type TemporalHistory<TEntity> = readonly TemporalSnapshot<TEntity>[];
 
+/**
+ * Bitemporal persistence port in the imperative (exception-raising) style.
+ *
+ * `delete(id)` is inherited from {@link Repository} and its bitemporal meaning
+ * is intentionally left to the implementation: it may close the current
+ * valid-time interval (a logical end-of-validity that preserves history) or
+ * physically purge the row's whole history. Pick one per adapter and document
+ * it — callers cannot tell which from this type. Prefer closing validity so
+ * `findAsOf`/`findHistory` stay meaningful for past instants.
+ */
 interface TemporalRepository<TEntity, TId> extends Repository<TEntity, TId> {
     findAsOf(id: TId, asOf: Date): Promise<TEntity | null>;
     findAtTransaction(id: TId, txTime: Date): Promise<TEntity | null>;
@@ -11,4 +23,25 @@ interface TemporalRepository<TEntity, TId> extends Repository<TEntity, TId> {
     save(entity: TEntity, validFrom?: Date): Promise<void>;
 }
 
-export type { TemporalHistory, TemporalRepository };
+/**
+ * `Result`-returning counterpart of {@link TemporalRepository}, aligned with the
+ * "errors as values" philosophy (mirrors the {@link Repository} /
+ * {@link ResultRepository} pair). The `delete` semantics note above applies
+ * unchanged.
+ */
+interface ResultTemporalRepository<TEntity, TId, TError = AppError>
+    extends ResultRepository<TEntity, TId, TError> {
+    findAsOf(id: TId, asOf: Date): Promise<Result<TEntity | null, TError>>;
+    findAtTransaction(
+        id: TId,
+        txTime: Date,
+    ): Promise<Result<TEntity | null, TError>>;
+    findHistory(id: TId): Promise<Result<TemporalHistory<TEntity>, TError>>;
+    save(entity: TEntity, validFrom?: Date): Promise<Result<void, TError>>;
+}
+
+export type {
+    ResultTemporalRepository,
+    TemporalHistory,
+    TemporalRepository,
+};

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

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

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

@@ -4,12 +4,15 @@ import type { AppError } from "../../errors/index.js";
 import type { Result } from "../../result/result.js";
 
 /**
- * Paginated result of a list query.
+ * Paginated result of a list query (offset-based).
  * Use as `Output` when the query returns a collection with pagination metadata.
+ * For cursor/keyset pagination, model your own `Output` type instead.
  */
 interface Page<T> {
     readonly items: readonly T[];
+    /** Total rows across all pages, ignoring `page`/`pageSize`. */
     readonly total: number;
+    /** 1-based page number (the first page is `1`, not `0`). */
     readonly page: number;
     readonly pageSize: number;
 }
@@ -17,11 +20,25 @@ interface Page<T> {
 /**
  * Cache strategy declared by the query type.
  * Infrastructure reads this value to decide whether and how to cache the result.
+ *
+ * These are pure descriptors: the type cannot enforce that a duration is finite
+ * and positive, so the caching adapter must validate `ttlMs` /
+ * `staleWhileRevalidateMs` (`> 0`, finite) before honoring the strategy.
  */
 type CacheStrategy =
     | { readonly kind: "NO_CACHE" }
     | { readonly kind: "TIME_TO_LIVE"; readonly ttlMs: number }
-    | { readonly kind: "STALE_WHILE_REVALIDATE"; readonly ttlMs: number };
+    | {
+          readonly kind: "STALE_WHILE_REVALIDATE";
+          /** How long the entry is served fresh. */
+          readonly ttlMs: number;
+          /**
+           * How long *after* `ttlMs` a stale entry may still be served while a
+           * background refresh runs. SWR needs both windows; a single TTL is
+           * ambiguous and each adapter would guess the second one.
+           */
+          readonly staleWhileRevalidateMs: number;
+      };
 
 type QueryOutput = object | string | number | boolean | bigint | symbol | null;
 
@@ -44,7 +61,12 @@ abstract class Query<
     Data extends QueryOutput = never,
     Failure = AppError,
 > extends UseCase<Input, Result<Data, Failure>> {
-    protected cacheStrategy(): CacheStrategy {
+    /**
+     * Declares how infrastructure should cache this query's result. Public so
+     * a caching adapter can actually read it off the instance; overrides must
+     * stay public.
+     */
+    public cacheStrategy(): CacheStrategy {
         return { kind: "NO_CACHE" };
     }
 }