@cullet/erp-core 1.2.0 → 1.4.0

package/KIT_CONTEXT.md

@@ -12,13 +12,15 @@ Núcleo arquitetural para sistemas ERP (e domínios transacionais com temporalid
 - **`result/`** — `Result<T, E>` e `Outcome` para retorno tipado da camada de aplicação.
 - **`application/`** — `UseCase` base, `commands/`, `queries/`, `ports/`. Casos de uso consomem portas e retornam `Result`.
 - **`policies/`** — catálogo, definições, resolução e avaliação de policies declarativas.
+- **`rbac/`** — RBAC zod-free (`./rbac`): `Permission`/`Role`/`Grant`/`Scope`, decisor `RbacAuthorizer`, `AuthorizerPort`.
+- **`abac/`** — ABAC zod-free (`./abac`): `AbacRule`/`AbacPolicySet` + combinação, decisor `AbacAuthorizer`, `AbacAuthorizerPort`, `CompositeAuthorizer`.
 - **`versioning/`** — utilidades de versionamento de agregados temporais.
 
 ## [key-decisions] Decisões-chave
 
 - **Domínio lança, aplicação retorna `Result`, infra traduz.** Não há `Result` no domínio.
 - **Sem lib de log/observabilidade no runtime.** Portas vivem em `application/ports/`; adapters são opt-in.
-- **Temporalidade interna ao kit** — o kit mantém suporte temporal no código-base, mas a API pública principal nao publica um `Timeline<T>` nem helpers temporais dedicados no barrel raiz.
+- **Temporalidade interna ao kit** — suporte temporal no código-base, mas a API pública não publica `Timeline<T>` nem helpers temporais no barrel raiz.
 - **Policies como dados**, não como if-statements: avaliáveis, compostas, serializáveis.
 - **Policies permitem disable sem remover código**: `PolicyDefinition` aceita `enabled: false` e o repositório ignora definições desabilitadas.
 - **Composição isolada é de primeira classe**: use `new CoreConfig()`, `new ContextResolverRegistry()` e `registerNamespacedContextResolversIn(...)` quando precisar evitar singletons compartilhados.
@@ -29,8 +31,8 @@ Núcleo arquitetural para sistemas ERP (e domínios transacionais com temporalid
 Implemente as portas em `application/ports/` para conectar a stack real:
 
 - `LoggerPort`, `MetricsPort`, `TracerPort` — observabilidade.
-- Repositórios específicos do seu domínio, sempre com verbo mínimo.
-- `AuthorizerPort` / `AuthenticatorPort` quando aplicável.
+- Repositórios do seu domínio, sempre com verbo mínimo.
+- `AuthorizerPort`/`AbacAuthorizerPort`/`AuthenticatorPort`.
 
 ## [non-goals] Não-objetivos
 

package/README.md

@@ -13,6 +13,8 @@ Para o sumário prompt-friendly veja [`KIT_CONTEXT.md`](./KIT_CONTEXT.md). Para
 - **Erros de aplicação** — `AppError` discriminada por `code`: `ValidationError`, `NotFoundError`, `ConflictError`, `AuthorizationError`, `IntegrationError`.
 - **Result** — `Result<T, E>` e `Outcome` para retorno tipado da aplicação.
 - **Policies** — `PolicyCatalog`, `PolicyDefinition`, `PolicyResolver`, `PolicyService` e tipos associados para avaliação declarativa.
+- **RBAC** — primitivas puras e zod-free no subpath [`./rbac`](#rbac-controle-de-acesso-por-papéis): `Permission`, `Role`, `Grant`, `Scope`, o decisor `RbacAuthorizer` e a `AuthorizerPort`. Veja a [seção dedicada](#rbac-controle-de-acesso-por-papéis).
+- **ABAC** — primitivas puras e zod-free no subpath [`./abac`](#abac-controle-de-acesso-por-atributos): `AbacRule`/`AbacPolicySet` com algoritmos de combinação, o decisor `AbacAuthorizer`, a `AbacAuthorizerPort` e o `CompositeAuthorizer`. Veja a [seção dedicada](#abac-controle-de-acesso-por-atributos).
 - **Application** — `UseCase`/`Command` (CQS, entrada `CommandInput` com `RequestedBy`), portas de persistência (`Repository` e a variante `ResultRepository`), `PolicyPort`, portas de observabilidade (`LoggerPort`, `MetricsPort`, `TracerPort`) e `mapPolicyEvaluationError`. Veja o [exemplo end-to-end](#exemplo-end-to-end).
 - **Exemplos** — rulesets de referência em `examples/rulesets/`, fora da superfície principal de domínio.
 
@@ -173,6 +175,164 @@ permite sinalizar not-found / concorrência otimista sem quebrar o fluxo. Uma
 implementação in-memory de referência está em
 [`src/examples/application/in-memory-account-repository.example.ts`](./src/examples/application/in-memory-account-repository.example.ts).
 
+## RBAC (controle de acesso por papéis)
+
+Primitivas puras e **zod-free** para responder "este ator pode executar esta
+ação neste recurso?". O subpath `@cullet/erp-core/rbac` não puxa `zod` — só
+instale `zod` se também for usar `./policies`. O decisor `RbacAuthorizer` é 100%
+puro (sem I/O) e devolve `Result`; carregar os `Grant`s do ator é responsabilidade
+do consumidor, atrás de uma `AuthorizerPort` — simétrico ao `PolicyPort`.
+
+```ts
+import {
+    Permission,
+    Role,
+    Grant,
+    Scope,
+    RbacAuthorizer,
+    type AuthorizerPort,
+    type AccessRequest,
+} from "@cullet/erp-core/rbac";
+import { RequestedBy } from "@cullet/erp-core";
+import { Result } from "@cullet/erp-core/result";
+import type { AuthorizationError } from "@cullet/erp-core/errors";
+
+// 1. Papéis e permissões são dados do SEU domínio — o kit só dá os tipos.
+const ROLES = {
+    cashier: Role.of("cashier", [
+        Permission.of("orders:read"),
+        Permission.of("orders:cancel"),
+    ]),
+    manager: Role.of("manager", [Permission.of("orders:*")]),
+    admin: Role.of("admin", [Permission.of("*:*")]), // super-permissão
+};
+
+// 2. Adapter da porta: carrega os Grants (do SEU store) e delega ao decisor puro.
+class RbacAuthorizerAdapter implements AuthorizerPort {
+    private readonly engine = new RbacAuthorizer();
+
+    constructor(
+        private readonly loadGrants: (
+            subject: string,
+        ) => Promise<readonly Grant[]>,
+    ) {}
+
+    async authorize(
+        request: AccessRequest,
+    ): Promise<Result<void, AuthorizationError>> {
+        const grants = await this.loadGrants(request.actor.raw);
+        const decision = this.engine.authorize(request, grants);
+        return decision.isErr()
+            ? Result.err(decision.error)
+            : Result.ok(undefined);
+    }
+}
+
+// 3. No caso de uso, injete só a porta e pergunte antes de mutar.
+const authorizer = new RbacAuthorizerAdapter(async (subject) => [
+    Grant.of({
+        subject: RequestedBy.parse(subject),
+        role: ROLES.cashier,
+        scope: Scope.of("school:42"),
+    }),
+]);
+
+const decision = await authorizer.authorize({
+    actor: RequestedBy.fromUser("550e8400-e29b-41d4-a716-446655440000"),
+    action: "order.cancel",
+    required: Permission.of("orders:cancel"),
+    resource: { type: "Order", id: "order-1" },
+    scope: Scope.of("school:42"),
+});
+// decision.isErr() → AuthorizationError com `reason`/`code`/`metadata` prontos
+// para a borda HTTP traduzir em 403.
+```
+
+O `reason` discriminado (`missing_role` / `missing_capability` / `out_of_scope`)
+e o `code` (`sec.authz.*`) já vêm preenchidos para a borda mapear sem re-derivar
+nada. Para regras declarativas além de "tem a permissão" (ABAC), `rbacContextFields(actor, grants)`
+projeta `actor.roles`/`actor.permissions` no `seed.fields` de uma policy de gate
+(aí sim com `./policies` + `zod`). O exemplo interno compilado e testado está em
+[`src/examples/application/authorize-cancel-order.example.ts`](./src/examples/application/authorize-cancel-order.example.ts).
+
+## ABAC (controle de acesso por atributos)
+
+Quando a decisão depende de **atributos** do sujeito, do recurso e do ambiente
+(não só de um papel estático), o subpath `@cullet/erp-core/abac` — também
+**zod-free** — dá um decisor puro que avalia regras `PERMIT`/`DENY` sobre esses
+atributos. `AbacRule` reusa a mesma DSL de condição do gate; `AbacPolicySet`
+combina as regras por um algoritmo (`deny-overrides` por padrão, mais
+`permit-overrides` / `first-applicable`) e é **fechado por padrão**. O decisor
+reusa o avaliador de condição puro do gate — sem arrastar `zod`.
+
+```ts
+import {
+    AbacRule,
+    AbacPolicySet,
+    AbacAuthorizer,
+    type AbacAuthorizerPort,
+    type AbacRequest,
+} from "@cullet/erp-core/abac";
+import { RequestedBy } from "@cullet/erp-core";
+import { Result } from "@cullet/erp-core/result";
+import type { AuthorizationError } from "@cullet/erp-core/errors";
+
+// 1. Regras são dados do SEU domínio (condição na DSL de gate, sobre atributos).
+const POLICIES = AbacPolicySet.of([
+    AbacRule.of({
+        id: "order.cancel.open-in-hours",
+        version: 1,
+        effect: "PERMIT",
+        condition: {
+            and: [
+                { field: "resource.status", op: "eq", value: "OPEN" },
+                { field: "env.businessHours", op: "eq", value: true },
+            ],
+        },
+    }),
+    AbacRule.of({
+        id: "order.cancel.deny-locked",
+        version: 1,
+        effect: "DENY", // deny-overrides ⇒ trava explícita vence qualquer PERMIT
+        condition: { field: "resource.locked", op: "eq", value: true },
+    }),
+]);
+
+// 2. Adapter da porta: resolve atributos dinâmicos e delega ao decisor puro.
+class AbacAuthorizerAdapter implements AbacAuthorizerPort {
+    private readonly engine = new AbacAuthorizer();
+
+    async authorize(
+        request: AbacRequest,
+    ): Promise<Result<void, AuthorizationError>> {
+        const decision = this.engine.authorize(request, POLICIES);
+        return decision.isErr()
+            ? Result.err(decision.error)
+            : Result.ok(undefined);
+    }
+}
+
+const authorizer = new AbacAuthorizerAdapter();
+const decision = await authorizer.authorize({
+    actor: RequestedBy.fromUser("550e8400-e29b-41d4-a716-446655440000"),
+    action: "order.cancel",
+    resource: { type: "Order", id: "order-1" },
+    attributes: {
+        resource: { status: "OPEN", locked: false },
+        environment: { businessHours: true },
+    },
+});
+// decision.isErr() → AuthorizationError (`policy_denied`, ou `forbidden` no
+// fail-closed) pronto para a borda traduzir em 403.
+```
+
+**RBAC ou ABAC?** RBAC responde "o ator _tem_ a capacidade?" (papel→permissão
+estático); ABAC responde "…_neste_ contexto?" (atributos do recurso/ambiente). Os
+dois compõem: o `CompositeAuthorizer` roda o RBAC e, se passar, refina com o ABAC.
+Para regras geridas como **dado** (versionadas, por tenant, vindas de JSON), use o
+motor `./policies` (aí sim com `zod`). O exemplo interno compilado e testado está
+em [`src/examples/application/authorize-cancel-order-abac.example.ts`](./src/examples/application/authorize-cancel-order-abac.example.ts).
+
 ## Composicao sem singletons
 
 Para isolamento por tenant, request ou teste, prefira instancias locais em vez

package/dist/abac/index.cjs

@@ -0,0 +1,7 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_rule = require("../rule.cjs");
+exports.AbacAuthorizer = require_rule.AbacAuthorizer;
+exports.AbacPolicySet = require_rule.AbacPolicySet;
+exports.AbacRule = require_rule.AbacRule;
+exports.CompositeAuthorizer = require_rule.CompositeAuthorizer;
+exports.abacContext = require_rule.abacContext;

package/dist/abac/index.d.cts

@@ -0,0 +1,2 @@
+import { a as AbacPolicySet, c as AbacRuleProps, d as AbacAuthorizerPort, f as AbacAttributes, i as AbacDecision, l as RuleEffect, n as CompositeAuthorizer, o as CombiningAlgorithm, p as AbacRequest, r as AbacAuthorizer, s as AbacRule, t as CompositeAccessRequest, u as abacContext } from "../composite-authorizer.cjs";
+export { AbacAttributes, AbacAuthorizer, AbacAuthorizerPort, AbacDecision, AbacPolicySet, AbacRequest, AbacRule, AbacRuleProps, CombiningAlgorithm, CompositeAccessRequest, CompositeAuthorizer, RuleEffect, abacContext };

package/dist/abac/index.d.ts

@@ -0,0 +1,2 @@
+import { a as AbacPolicySet, c as AbacRuleProps, d as AbacAuthorizerPort, f as AbacAttributes, i as AbacDecision, l as RuleEffect, n as CompositeAuthorizer, o as CombiningAlgorithm, p as AbacRequest, r as AbacAuthorizer, s as AbacRule, t as CompositeAccessRequest, u as abacContext } from "../composite-authorizer.js";
+export { AbacAttributes, AbacAuthorizer, AbacAuthorizerPort, AbacDecision, AbacPolicySet, AbacRequest, AbacRule, AbacRuleProps, CombiningAlgorithm, CompositeAccessRequest, CompositeAuthorizer, RuleEffect, abacContext };

package/dist/abac/index.js

@@ -0,0 +1,2 @@
+import { a as abacContext, i as AbacAuthorizer, n as AbacPolicySet, r as CompositeAuthorizer, t as AbacRule } from "../rule.js";
+export { AbacAuthorizer, AbacPolicySet, AbacRule, CompositeAuthorizer, abacContext };

package/dist/app-error.cjs

@@ -0,0 +1,193 @@
+//#region src/core/errors/error-codes.ts
+const ErrorCodes = {
+	authentication: {
+		missingToken: "sec.authn.missing_token",
+		invalidToken: "sec.authn.invalid_token",
+		expiredToken: "sec.authn.expired_token",
+		invalidCredentials: "sec.authn.invalid_credentials"
+	},
+	authorization: {
+		forbidden: "sec.authz.forbidden",
+		policyDenied: "sec.authz.policy_denied",
+		missingRole: "sec.authz.missing_role",
+		missingCapability: "sec.authz.missing_capability",
+		outOfScope: "sec.authz.out_of_scope"
+	},
+	businessRuleViolation: "business_rule_violation",
+	conflict: {
+		alreadyExists: "conf.already_exists",
+		duplicate: "conf.duplicate",
+		uniqueViolation: "conf.unique_violation"
+	},
+	idempotency: {
+		keyMissing: "idemp.key_missing",
+		inProgress: "idemp.in_progress",
+		payloadMismatch: "idemp.payload_mismatch",
+		replayNotSupported: "idemp.replay_not_supported"
+	},
+	integration: {
+		timeout: "int.timeout",
+		unreachable: "int.unreachable",
+		badResponse: "int.bad_response"
+	},
+	legacyIncompatible: "legacy_incompatible",
+	notFound: "not_found",
+	serialization: {
+		deserializePrefix: "ser.des",
+		serializePrefix: "ser.ser"
+	},
+	temporal: {
+		expired: "tmp.expired",
+		notYetValid: "tmp.not_yet_valid"
+	},
+	unexpected: "unexpected",
+	validation: "validation_error"
+};
+function serializationErrorCode(direction, category) {
+	return `${direction === "deserialize" ? ErrorCodes.serialization.deserializePrefix : ErrorCodes.serialization.serializePrefix}.${category}`;
+}
+//#endregion
+//#region src/core/errors/utils/json-safe.ts
+const NON_SERIALIZABLE_PLACEHOLDER = "[NonSerializable]";
+const CIRCULAR_REFERENCE_PLACEHOLDER = "[Circular]";
+function isPlainObject(value) {
+	if (value === null || typeof value !== "object") return false;
+	const proto = Object.getPrototypeOf(value);
+	return proto === Object.prototype || proto === null;
+}
+function sanitizeValue(value, seen) {
+	if (value === null) return null;
+	const type = typeof value;
+	if (type === "string" || type === "number" || type === "boolean") return value;
+	if (type === "bigint" || type === "function" || type === "symbol" || value === void 0) return NON_SERIALIZABLE_PLACEHOLDER;
+	if (Array.isArray(value)) {
+		if (seen.has(value)) return CIRCULAR_REFERENCE_PLACEHOLDER;
+		seen.add(value);
+		const sanitized = value.map((item) => sanitizeValue(item, seen));
+		seen.delete(value);
+		return sanitized;
+	}
+	if (value instanceof Date) return NON_SERIALIZABLE_PLACEHOLDER;
+	if (!isPlainObject(value)) return NON_SERIALIZABLE_PLACEHOLDER;
+	if (seen.has(value)) return CIRCULAR_REFERENCE_PLACEHOLDER;
+	seen.add(value);
+	const result = {};
+	for (const [key, val] of Object.entries(value)) result[key] = sanitizeValue(val, seen);
+	seen.delete(value);
+	return result;
+}
+/**
+* Ensures metadata is JSON-serializable.
+*
+* **Allowed:** string, number, boolean, null, arrays, and plain objects.
+*
+* **Converted to placeholder:** Date, BigInt, class instances, functions,
+* symbols, undefined, and circular references (which would otherwise make
+* `JSON.stringify` throw).
+*
+* @throws {TypeError} If `input` is not a plain object at the root level.
+*/
+function assertJsonSafeMetadata(input) {
+	if (input === void 0) return {};
+	if (!isPlainObject(input)) throw new TypeError("metadata must be a plain object (Record<string, unknown>).");
+	return sanitizeValue(input, /* @__PURE__ */ new WeakSet());
+}
+//#endregion
+//#region src/core/errors/app-error.ts
+/**
+* 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`.
+*/
+var AppError = class extends Error {
+	/**
+	* 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.
+	*/
+	constructor(message, code, options) {
+		super(message);
+		this.name = new.target.name;
+		this.code = code;
+		this.cause = options?.cause;
+		this.type = options?.type;
+		this.severity = options?.severity;
+		this.correlationId = options?.correlationId;
+		this.requestId = options?.requestId;
+		this.commandId = options?.commandId;
+		this.createdAtIso = options?.createdAtIso ?? (/* @__PURE__ */ new Date()).toISOString();
+		this.publicMessage = options?.publicMessage;
+		this.metadata = options?.metadata ? assertJsonSafeMetadata(options.metadata) : void 0;
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
+	/**
+	* Returns a JSON-safe representation of the error.
+	* Does NOT include `cause` by default (to avoid leaking internal details).
+	*/
+	toJSON() {
+		const payload = {
+			name: this.name,
+			code: this.code,
+			message: this.message,
+			createdAtIso: this.createdAtIso
+		};
+		if (this.type !== void 0) payload.type = this.type;
+		if (this.severity !== void 0) payload.severity = this.severity;
+		if (this.publicMessage !== void 0) payload.publicMessage = this.publicMessage;
+		if (this.metadata !== void 0) payload.metadata = this.metadata;
+		if (this.correlationId !== void 0) payload.correlationId = this.correlationId;
+		if (this.requestId !== void 0) payload.requestId = this.requestId;
+		if (this.commandId !== void 0) payload.commandId = this.commandId;
+		return payload;
+	}
+};
+//#endregion
+Object.defineProperty(exports, "AppError", {
+	enumerable: true,
+	get: function() {
+		return AppError;
+	}
+});
+Object.defineProperty(exports, "ErrorCodes", {
+	enumerable: true,
+	get: function() {
+		return ErrorCodes;
+	}
+});
+Object.defineProperty(exports, "assertJsonSafeMetadata", {
+	enumerable: true,
+	get: function() {
+		return assertJsonSafeMetadata;
+	}
+});
+Object.defineProperty(exports, "serializationErrorCode", {
+	enumerable: true,
+	get: function() {
+		return serializationErrorCode;
+	}
+});
+
+//# sourceMappingURL=app-error.cjs.map

package/dist/app-error.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-error.cjs","names":[],"sources":["../src/core/errors/error-codes.ts","../src/core/errors/utils/json-safe.ts","../src/core/errors/app-error.ts"],"sourcesContent":["const ErrorCodes = {\n    authentication: {\n        missingToken: \"sec.authn.missing_token\",\n        invalidToken: \"sec.authn.invalid_token\",\n        expiredToken: \"sec.authn.expired_token\",\n        invalidCredentials: \"sec.authn.invalid_credentials\",\n    },\n    authorization: {\n        forbidden: \"sec.authz.forbidden\",\n        policyDenied: \"sec.authz.policy_denied\",\n        missingRole: \"sec.authz.missing_role\",\n        missingCapability: \"sec.authz.missing_capability\",\n        outOfScope: \"sec.authz.out_of_scope\",\n    },\n    businessRuleViolation: \"business_rule_violation\",\n    conflict: {\n        alreadyExists: \"conf.already_exists\",\n        duplicate: \"conf.duplicate\",\n        uniqueViolation: \"conf.unique_violation\",\n    },\n    idempotency: {\n        keyMissing: \"idemp.key_missing\",\n        inProgress: \"idemp.in_progress\",\n        payloadMismatch: \"idemp.payload_mismatch\",\n        replayNotSupported: \"idemp.replay_not_supported\",\n    },\n    integration: {\n        timeout: \"int.timeout\",\n        unreachable: \"int.unreachable\",\n        badResponse: \"int.bad_response\",\n    },\n    legacyIncompatible: \"legacy_incompatible\",\n    notFound: \"not_found\",\n    serialization: {\n        deserializePrefix: \"ser.des\",\n        serializePrefix: \"ser.ser\",\n    },\n    temporal: {\n        expired: \"tmp.expired\",\n        notYetValid: \"tmp.not_yet_valid\",\n    },\n    unexpected: \"unexpected\",\n    validation: \"validation_error\",\n} as const;\n\ntype SerializationCodeDirection = \"deserialize\" | \"serialize\";\n\nfunction serializationErrorCode(\n    direction: SerializationCodeDirection,\n    category: string,\n): string {\n    const prefix =\n        direction === \"deserialize\"\n            ? ErrorCodes.serialization.deserializePrefix\n            : ErrorCodes.serialization.serializePrefix;\n\n    return `${prefix}.${category}`;\n}\n\nexport { ErrorCodes, serializationErrorCode };\nexport type { SerializationCodeDirection };\n","// Utilities for ensuring metadata is JSON-serializable.\n\nimport type { JsonSafeRecord, JsonSafeValue } from \"../types.js\";\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Constants\n// ─────────────────────────────────────────────────────────────────────────────\n\nconst NON_SERIALIZABLE_PLACEHOLDER = \"[NonSerializable]\";\nconst CIRCULAR_REFERENCE_PLACEHOLDER = \"[Circular]\";\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Internal helpers\n// ─────────────────────────────────────────────────────────────────────────────\n\nfunction isPlainObject(value: unknown): value is Record<string, unknown> {\n    if (value === null || typeof value !== \"object\") return false;\n    const proto = Object.getPrototypeOf(value);\n    return proto === Object.prototype || proto === null;\n}\n\n// `seen` tracks the ancestors on the current traversal branch (a DFS path), not\n// every object visited. This collapses true circular references to a placeholder\n// while still serializing the same object referenced more than once across\n// sibling branches (a DAG) — matching `JSON.stringify`, which only rejects\n// cycles, not shared references.\nfunction sanitizeValue(value: unknown, seen: WeakSet<object>): JsonSafeValue {\n    // Null passthrough\n    if (value === null) return null;\n\n    const type = typeof value;\n\n    // Primitives\n    if (type === \"string\" || type === \"number\" || type === \"boolean\") {\n        return value as JsonSafeValue;\n    }\n\n    // Non-serializable primitives\n    if (\n        type === \"bigint\" ||\n        type === \"function\" ||\n        type === \"symbol\" ||\n        value === undefined\n    ) {\n        return NON_SERIALIZABLE_PLACEHOLDER;\n    }\n\n    // Arrays (recursive)\n    if (Array.isArray(value)) {\n        if (seen.has(value)) return CIRCULAR_REFERENCE_PLACEHOLDER;\n        seen.add(value);\n        const sanitized = value.map((item) => sanitizeValue(item, seen));\n        seen.delete(value);\n        return sanitized;\n    }\n\n    // Date → placeholder (could also use .toISOString() if preferred)\n    if (value instanceof Date) {\n        return NON_SERIALIZABLE_PLACEHOLDER;\n    }\n\n    // Class instances and non-plain objects → placeholder\n    if (!isPlainObject(value)) {\n        return NON_SERIALIZABLE_PLACEHOLDER;\n    }\n\n    // Plain object (recursive)\n    if (seen.has(value)) return CIRCULAR_REFERENCE_PLACEHOLDER;\n    seen.add(value);\n    const result: Record<string, JsonSafeValue> = {};\n    for (const [key, val] of Object.entries(value)) {\n        result[key] = sanitizeValue(val, seen);\n    }\n    seen.delete(value);\n    return result;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Public API\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Ensures metadata is JSON-serializable.\n *\n * **Allowed:** string, number, boolean, null, arrays, and plain objects.\n *\n * **Converted to placeholder:** Date, BigInt, class instances, functions,\n * symbols, undefined, and circular references (which would otherwise make\n * `JSON.stringify` throw).\n *\n * @throws {TypeError} If `input` is not a plain object at the root level.\n */\nfunction assertJsonSafeMetadata(input: unknown): JsonSafeRecord {\n    if (input === undefined) {\n        return {};\n    }\n\n    if (!isPlainObject(input)) {\n        throw new TypeError(\n            \"metadata must be a plain object (Record<string, unknown>).\",\n        );\n    }\n\n    return sanitizeValue(input, new WeakSet<object>()) as JsonSafeRecord;\n}\n\nexport {\n    assertJsonSafeMetadata,\n    CIRCULAR_REFERENCE_PLACEHOLDER,\n    NON_SERIALIZABLE_PLACEHOLDER,\n};\n","// Base application error for the domain/application layer.\n// Encapsulates a code, optional cause, and JSON-safe metadata.\n\nimport type {\n    AppErrorOptions,\n    ErrorSeverity,\n    JsonSafeRecord,\n} from \"./types.js\";\nimport { assertJsonSafeMetadata } from \"./utils/index.js\";\n\n// ─────────────────────────────────────────────────────────────────────────────\n// AppError (abstract base class)\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Root of the application/domain error hierarchy. Every error the system raises\n * on purpose extends `AppError`, which gives callers a single `instanceof` to\n * catch and a uniform, serializable shape to log and transport.\n *\n * Beyond the native `Error` message it carries a stable `code` (the contract the\n * outside world matches on), an optional non-leaking `publicMessage`, a\n * severity, JSON-safe `metadata`, and the correlation/request/command ids that\n * stitch an error back to the request that produced it. The metadata is\n * validated as JSON-safe on construction, so a logger can serialize any\n * `AppError` without hitting a circular reference or a non-serializable value.\n *\n * Abstract on purpose: callers should throw a specific subclass (e.g.\n * {@link ValidationError}, {@link NotFoundError}) so the `code` and shape are\n * meaningful, never a bare `AppError`.\n */\nabstract class AppError extends Error {\n    public readonly code: string;\n    public readonly cause?: unknown;\n    public readonly metadata?: JsonSafeRecord;\n    public readonly type?: string;\n    public readonly severity?: ErrorSeverity;\n    public readonly createdAtIso: string;\n    public readonly publicMessage?: string;\n    /**\n     * Identifies a single execution \"story\" in the system. All operations\n     * related to the same logical flow must share the same correlationId.\n     */\n    public readonly correlationId?: string;\n    /**\n     * Identifies a specific technical request attempt (each retry may produce\n     * a new requestId), even when the correlationId stays the same.\n     */\n    public readonly requestId?: string;\n    /**\n     * Marks the business intent / idempotency key; stays the same across\n     * technical retries and multiple requests that represent the same intent.\n     */\n    public readonly commandId?: string;\n\n    /**\n     * Builds the common error envelope shared by every subclass.\n     *\n     * `name` is taken from `new.target` so the thrown instance reports its\n     * concrete subclass name (not `\"AppError\"`), and the prototype is re-pinned\n     * via `setPrototypeOf` so `instanceof` keeps working after transpilation to\n     * older targets where extending built-ins breaks the chain. `createdAtIso`\n     * defaults to now, and `metadata` is validated as JSON-safe so the error is\n     * always serializable.\n     *\n     * Declared `protected`: instantiate a concrete subclass, never `AppError`.\n     *\n     * @param message - The internal, developer-facing message.\n     * @param code - The stable machine-readable code callers match on.\n     * @param options - Optional cause, metadata, severity, and correlation ids.\n     * @throws When `options.metadata` contains a value that is not JSON-safe.\n     */\n    protected constructor(\n        message: string,\n        code: string,\n        options?: AppErrorOptions,\n    ) {\n        super(message);\n\n        this.name = new.target.name;\n        this.code = code;\n        this.cause = options?.cause;\n        this.type = options?.type;\n        this.severity = options?.severity;\n        this.correlationId = options?.correlationId;\n        this.requestId = options?.requestId;\n        this.commandId = options?.commandId;\n        this.createdAtIso = options?.createdAtIso ?? new Date().toISOString();\n        this.publicMessage = options?.publicMessage;\n\n        this.metadata = options?.metadata\n            ? assertJsonSafeMetadata(options.metadata)\n            : undefined;\n\n        Object.setPrototypeOf(this, new.target.prototype);\n    }\n\n    /**\n     * Returns a JSON-safe representation of the error.\n     * Does NOT include `cause` by default (to avoid leaking internal details).\n     */\n    public toJSON(): Record<string, unknown> {\n        const payload: Record<string, unknown> = {\n            name: this.name,\n            code: this.code,\n            message: this.message,\n            createdAtIso: this.createdAtIso,\n        };\n\n        // Optional fields are emitted only when defined, so the serialized\n        // shape never carries `undefined`-valued keys (consistent with how the\n        // correlation/request/command ids are handled).\n        if (this.type !== undefined) payload.type = this.type;\n        if (this.severity !== undefined) payload.severity = this.severity;\n        if (this.publicMessage !== undefined)\n            payload.publicMessage = this.publicMessage;\n        if (this.metadata !== undefined) payload.metadata = this.metadata;\n        if (this.correlationId !== undefined)\n            payload.correlationId = this.correlationId;\n        if (this.requestId !== undefined) payload.requestId = this.requestId;\n        if (this.commandId !== undefined) payload.commandId = this.commandId;\n\n        return payload;\n    }\n}\n\nexport { AppError };\n"],"mappings":"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"}

package/dist/app-error.d.cts

@@ -0,0 +1,108 @@
+//#region src/core/errors/types.d.ts
+type ErrorSeverity = "low" | "medium" | "high" | "critical";
+type JsonSafePrimitive = string | number | boolean | null;
+type JsonSafeValue = JsonSafePrimitive | JsonSafeValue[] | {
+  [key: string]: JsonSafeValue;
+};
+type JsonSafeRecord = Record<string, JsonSafeValue>;
+/**
+ * Options accepted by the AppError constructor.
+ * Subclasses can extend or pick from this type.
+ */
+type AppErrorOptions = {
+  /** Original error or exception that caused this error. */
+  cause?: unknown;
+  /** Arbitrary key-value metadata (will be sanitized to JSON-safe values). */
+  metadata?: Record<string, unknown>;
+  /** Error category/type for grouping (e.g., "authentication", "validation"). */
+  type?: string;
+  /** severity level for alerting/logging prioritization. */
+  severity?: ErrorSeverity;
+  /**
+   * Identifies a single execution "story" in the system. All operations
+   * related to the same logical flow must share the same correlationId.
+   */
+  correlationId?: string;
+  /**
+   * Identifies a specific technical request attempt (each retry may produce
+   * a new requestId), even when the correlationId stays the same.
+   */
+  requestId?: string;
+  /**
+   * Identifies a unique business intent (idempotency key); stays the same
+   * across technical retries and multiple requests that represent the same intent.
+   */
+  commandId?: string;
+  /** ISO timestamp of when the error was created (defaults to now). */
+  createdAtIso?: string;
+  /** Safe message that can be exposed to end users (no internal details). */
+  publicMessage?: string;
+};
+//#endregion
+//#region src/core/errors/app-error.d.ts
+/**
+ * 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`.
+ */
+declare abstract class AppError extends Error {
+  readonly code: string;
+  readonly cause?: unknown;
+  readonly metadata?: JsonSafeRecord;
+  readonly type?: string;
+  readonly severity?: ErrorSeverity;
+  readonly createdAtIso: string;
+  readonly publicMessage?: string;
+  /**
+   * Identifies a single execution "story" in the system. All operations
+   * related to the same logical flow must share the same correlationId.
+   */
+  readonly correlationId?: string;
+  /**
+   * Identifies a specific technical request attempt (each retry may produce
+   * a new requestId), even when the correlationId stays the same.
+   */
+  readonly requestId?: string;
+  /**
+   * Marks the business intent / idempotency key; stays the same across
+   * technical retries and multiple requests that represent the same intent.
+   */
+  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, options?: AppErrorOptions);
+  /**
+   * Returns a JSON-safe representation of the error.
+   * Does NOT include `cause` by default (to avoid leaking internal details).
+   */
+  toJSON(): Record<string, unknown>;
+}
+//#endregion
+export { JsonSafeRecord as a, JsonSafePrimitive as i, AppErrorOptions as n, JsonSafeValue as o, ErrorSeverity as r, AppError as t };
+//# sourceMappingURL=app-error.d.cts.map