@cullet/erp-core 1.4.0 → 2.0.0

package/dist/authorization-error.d.ts

@@ -16,9 +16,13 @@ type AuthorizationErrorMetadata = {
     type: string;
     id?: string;
   };
-  /** Optional: actor (do not include sensitive data) */
+  /**
+   * Optional: the acting principal (do not include sensitive data). `actorId`
+   * is the raw `RequestedBy` value — a user UUID *or* a `"system:<job>"`
+   * identity — so it must not be assumed to be a human user.
+   */
   actor?: {
-    userId: string;
+    actorId: string;
     role?: string;
   };
   /** Optional: expected requirement */

package/dist/authorization-error.js

@@ -1,4 +1,48 @@
 import { r as ErrorCodes, t as AppError } from "./app-error.js";
+//#region src/core/errors/utils/factory-helpers.ts
+/** The envelope fields AppError understands; everything else is metadata. */
+const APP_ERROR_OPTION_KEYS = [
+	"cause",
+	"type",
+	"severity",
+	"correlationId",
+	"requestId",
+	"commandId",
+	"createdAtIso",
+	"publicMessage"
+];
+/**
+* Picks the AppError envelope fields out of a flat factory input, so they can
+* be forwarded to the constructor as options instead of leaking into metadata.
+*/
+function pickAppErrorOptions(input) {
+	return {
+		cause: input?.cause,
+		type: input?.type,
+		severity: input?.severity,
+		correlationId: input?.correlationId,
+		requestId: input?.requestId,
+		commandId: input?.commandId,
+		createdAtIso: input?.createdAtIso,
+		publicMessage: input?.publicMessage
+	};
+}
+/**
+* The complement of {@link pickAppErrorOptions}: everything that is *not* an
+* AppError envelope field, i.e. the caller-supplied metadata. Keeps the cause
+* and the public message out of the internal data block.
+*/
+function stripAppErrorOptions(input) {
+	const result = { ...input };
+	for (const key of APP_ERROR_OPTION_KEYS) delete result[key];
+	return result;
+}
+/** Drops keys whose value is `undefined` (mirrors how JSON.stringify treats them). */
+function compactMetadata(input) {
+	if (!input) return void 0;
+	return Object.fromEntries(Object.entries(input).filter(([, value]) => value !== void 0));
+}
+//#endregion
 //#region src/core/errors/authorization-error.ts
 /**
 * Raised when an authenticated actor is not allowed to perform a business
@@ -44,7 +88,7 @@ var AuthorizationError = class AuthorizationError extends AppError {
 				reason: "forbidden",
 				...extractMetadataOnly(input)
 			},
-			...extractAppErrorOptions(input)
+			...pickAppErrorOptions(input)
 		});
 	}
 	/**
@@ -66,7 +110,7 @@ var AuthorizationError = class AuthorizationError extends AppError {
 				...extractMetadataOnly(input),
 				decision: "deny"
 			},
-			...extractAppErrorOptions(input)
+			...pickAppErrorOptions(input)
 		});
 	}
 	/**
@@ -87,7 +131,7 @@ var AuthorizationError = class AuthorizationError extends AppError {
 				reason: "missing_role",
 				...extractMetadataOnly(input)
 			},
-			...extractAppErrorOptions(input)
+			...pickAppErrorOptions(input)
 		});
 	}
 	/**
@@ -106,7 +150,7 @@ var AuthorizationError = class AuthorizationError extends AppError {
 				reason: "missing_capability",
 				...extractMetadataOnly(input)
 			},
-			...extractAppErrorOptions(input)
+			...pickAppErrorOptions(input)
 		});
 	}
 	/**
@@ -126,27 +170,15 @@ var AuthorizationError = class AuthorizationError extends AppError {
 				reason: "out_of_scope",
 				...extractMetadataOnly(input)
 			},
-			...extractAppErrorOptions(input)
+			...pickAppErrorOptions(input)
 		});
 	}
 };
-function extractAppErrorOptions(options) {
-	return {
-		cause: options?.cause,
-		type: options?.type,
-		severity: options?.severity,
-		correlationId: options?.correlationId,
-		requestId: options?.requestId,
-		commandId: options?.commandId,
-		createdAtIso: options?.createdAtIso,
-		publicMessage: options?.publicMessage
-	};
-}
 function extractMetadataOnly(input) {
 	const { cause, type, severity, correlationId, requestId, commandId, createdAtIso, publicMessage, ...metadata } = input;
 	return metadata;
 }
 //#endregion
-export { AuthorizationError as t };
+export { stripAppErrorOptions as i, compactMetadata as n, pickAppErrorOptions as r, AuthorizationError as t };
 
 //# sourceMappingURL=authorization-error.js.map

package/dist/authorization-error.js.map

@@ -1 +1 @@
-{"version":3,"file":"authorization-error.js","names":[],"sources":["../src/core/errors/authorization-error.ts"],"sourcesContent":["import { AppError } from \"./app-error.js\";\nimport { ErrorCodes } from \"./error-codes.js\";\nimport type { AppErrorOptions, ErrorSeverity } from \"./types.js\";\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Types\n// ─────────────────────────────────────────────────────────────────────────────\n\ntype AuthorizationErrorReason =\n    | \"forbidden\"\n    | \"missing_role\"\n    | \"missing_capability\"\n    | \"out_of_scope\"\n    | \"outside_time_window\"\n    | \"policy_denied\"\n    | \"unknown\";\n\ntype AuthorizationRequirement = {\n    role?: string;\n    capability?: string;\n    scope?: string; // e.g.: \"school:{id}\" or \"class:{id}\"\n};\n\ntype AuthorizationErrorMetadata = {\n    reason: AuthorizationErrorReason;\n\n    /** Stable action you evaluated (not an HTTP route — a \"business action\") */\n    action: string;\n\n    /** Resource identification (without leaking the full payload) */\n    resource?: { type: string; id?: string };\n\n    /** Optional: actor (do not include sensitive data) */\n    actor?: { userId: string; role?: string };\n\n    /** Optional: expected requirement */\n    required?: AuthorizationRequirement;\n\n    /** Optional: policy (when you already have PolicyEvaluation or similar) */\n    policyId?: string;\n    policyVersion?: number;\n    evaluatedAtIso?: string;\n    decision?: \"allow\" | \"deny\";\n    reasonCode?: string;\n\n    /** Optional: additional non-sensitive info */\n    details?: string;\n};\n\n/**\n * Options for AuthorizationError factory methods.\n * Combines metadata fields (except 'reason') with common AppError options.\n */\ntype AuthorizationErrorFactoryOptions = Omit<\n    AuthorizationErrorMetadata,\n    \"reason\"\n> &\n    Omit<AppErrorOptions, \"metadata\">;\n\n// ─────────────────────────────────────────────────────────────────────────────\n// AuthorizationError\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Raised when an authenticated actor is not allowed to perform a business\n * action — the \"you may not\" error, distinct from authentication (\"who are\n * you\"). Maps to an HTTP 403 at the edge.\n *\n * The discriminating {@link reason} records *why* access was denied (a flat\n * forbid, a missing role/capability, an out-of-scope target, or a policy\n * decision) so the boundary can shape the response without re-deriving it. The\n * metadata is deliberately built around a stable business `action` and a\n * type/id resource reference rather than an HTTP route or full payload, keeping\n * sensitive data out of logs. Instances are frozen. Construct through the\n * static factories, never directly.\n */\nclass AuthorizationError extends AppError {\n    public readonly reason: AuthorizationErrorReason;\n\n    private constructor(params: {\n        message: string;\n        code: string;\n        reason: AuthorizationErrorReason;\n        metadata: AuthorizationErrorMetadata;\n        cause?: unknown;\n        type?: string;\n        severity?: ErrorSeverity;\n        correlationId?: string;\n        requestId?: string;\n        commandId?: string;\n        createdAtIso?: string;\n        publicMessage?: string;\n    }) {\n        super(params.message, params.code, {\n            cause: params.cause,\n            metadata: params.metadata,\n            type: params.type,\n            severity: params.severity,\n            correlationId: params.correlationId,\n            requestId: params.requestId,\n            commandId: params.commandId,\n            createdAtIso: params.createdAtIso,\n            publicMessage: params.publicMessage,\n        });\n\n        this.reason = params.reason;\n        Object.freeze(this);\n    }\n\n    // ─────────────────────────────────────────────────────────────────────────\n    // Factories\n    // ─────────────────────────────────────────────────────────────────────────\n\n    /**\n     * A flat denial with no more specific reason — the actor simply may not\n     * perform this action. Reach for a more precise factory\n     * ({@link AuthorizationError.missingCapability}, {@link AuthorizationError.outOfScope},\n     * {@link AuthorizationError.policyDenied}) when the cause is known.\n     */\n    static forbidden(\n        input: AuthorizationErrorFactoryOptions,\n    ): AuthorizationError {\n        return new AuthorizationError({\n            message: \"Action not allowed\",\n            code: ErrorCodes.authorization.forbidden,\n            reason: \"forbidden\",\n            metadata: { reason: \"forbidden\", ...extractMetadataOnly(input) },\n            ...extractAppErrorOptions(input),\n        });\n    }\n\n    /**\n     * The action was denied by an evaluated policy. Captures the deciding\n     * policy's id, version, and evaluation instant into the metadata (with\n     * `decision: \"deny\"`) so the denial is auditable back to the exact policy\n     * that produced it.\n     *\n     * @param input - Factory options plus the required `policyId`,\n     *   `policyVersion`, and `evaluatedAtIso` of the deciding policy.\n     */\n    static policyDenied(\n        input: AuthorizationErrorFactoryOptions & {\n            policyId: string;\n            policyVersion: number;\n            evaluatedAtIso: string;\n        },\n    ): AuthorizationError {\n        return new AuthorizationError({\n            message: \"Action denied by policy\",\n            code: ErrorCodes.authorization.policyDenied,\n            reason: \"policy_denied\",\n            metadata: {\n                reason: \"policy_denied\",\n                ...extractMetadataOnly(input),\n                decision: \"deny\",\n            },\n            ...extractAppErrorOptions(input),\n        });\n    }\n\n    /**\n     * The actor holds no role at all that bears on the action — the most basic\n     * denial, distinct from {@link AuthorizationError.missingCapability} (which\n     * means the actor *has* roles, just none granting the required capability).\n     * The expected {@link AuthorizationRequirement} is recorded so the boundary\n     * can tell the caller what grant is missing.\n     *\n     * @param input - Factory options plus the `required` role/capability/scope.\n     */\n    static missingRole(\n        input: AuthorizationErrorFactoryOptions & {\n            required: AuthorizationRequirement;\n        },\n    ): AuthorizationError {\n        return new AuthorizationError({\n            message: \"Missing required role to perform the action\",\n            code: ErrorCodes.authorization.missingRole,\n            reason: \"missing_role\",\n            metadata: {\n                reason: \"missing_role\",\n                ...extractMetadataOnly(input),\n            },\n            ...extractAppErrorOptions(input),\n        });\n    }\n\n    /**\n     * The actor lacks a required role or capability. The expected\n     * {@link AuthorizationRequirement} is recorded so the boundary can tell the\n     * caller precisely what grant is missing.\n     *\n     * @param input - Factory options plus the `required` role/capability/scope.\n     */\n    static missingCapability(\n        input: AuthorizationErrorFactoryOptions & {\n            required: AuthorizationRequirement;\n        },\n    ): AuthorizationError {\n        return new AuthorizationError({\n            message: \"Insufficient capability to perform the action\",\n            code: ErrorCodes.authorization.missingCapability,\n            reason: \"missing_capability\",\n            metadata: {\n                reason: \"missing_capability\",\n                ...extractMetadataOnly(input),\n            },\n            ...extractAppErrorOptions(input),\n        });\n    }\n\n    /**\n     * The actor may perform the action in general, but not on *this* target —\n     * the resource falls outside the actor's permitted scope (e.g. a different\n     * school or tenant than the one they are bound to).\n     *\n     * @param input - Factory options plus the optional `required` scope that the\n     *   target failed to satisfy.\n     */\n    static outOfScope(\n        input: AuthorizationErrorFactoryOptions & {\n            required?: AuthorizationRequirement;\n        },\n    ): AuthorizationError {\n        return new AuthorizationError({\n            message: \"Action outside the allowed scope\",\n            code: ErrorCodes.authorization.outOfScope,\n            reason: \"out_of_scope\",\n            metadata: { reason: \"out_of_scope\", ...extractMetadataOnly(input) },\n            ...extractAppErrorOptions(input),\n        });\n    }\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Helpers\n// ─────────────────────────────────────────────────────────────────────────────\n\nfunction extractAppErrorOptions(options?: Partial<AppErrorOptions>) {\n    return {\n        cause: options?.cause,\n        type: options?.type,\n        severity: options?.severity,\n        correlationId: options?.correlationId,\n        requestId: options?.requestId,\n        commandId: options?.commandId,\n        createdAtIso: options?.createdAtIso,\n        publicMessage: options?.publicMessage,\n    };\n}\n\nfunction extractMetadataOnly(\n    input: AuthorizationErrorFactoryOptions,\n): Omit<AuthorizationErrorMetadata, \"reason\"> {\n    const {\n        cause,\n        type,\n        severity,\n        correlationId,\n        requestId,\n        commandId,\n        createdAtIso,\n        publicMessage,\n        ...metadata\n    } = input;\n    return metadata;\n}\n\nexport { AuthorizationError };\nexport type {\n    AuthorizationErrorMetadata,\n    AuthorizationErrorReason,\n    AuthorizationRequirement,\n};\n"],"mappings":";;;;;;;;;;;;;;;AA4EA,IAAM,qBAAN,MAAM,2BAA2B,SAAS;CAGtC,YAAoB,QAajB;EACC,MAAM,OAAO,SAAS,OAAO,MAAM;GAC/B,OAAO,OAAO;GACd,UAAU,OAAO;GACjB,MAAM,OAAO;GACb,UAAU,OAAO;GACjB,eAAe,OAAO;GACtB,WAAW,OAAO;GAClB,WAAW,OAAO;GAClB,cAAc,OAAO;GACrB,eAAe,OAAO;EAC1B,CAAC;EAED,KAAK,SAAS,OAAO;EACrB,OAAO,OAAO,IAAI;CACtB;;;;;;;CAYA,OAAO,UACH,OACkB;EAClB,OAAO,IAAI,mBAAmB;GAC1B,SAAS;GACT,MAAM,WAAW,cAAc;GAC/B,QAAQ;GACR,UAAU;IAAE,QAAQ;IAAa,GAAG,oBAAoB,KAAK;GAAE;GAC/D,GAAG,uBAAuB,KAAK;EACnC,CAAC;CACL;;;;;;;;;;CAWA,OAAO,aACH,OAKkB;EAClB,OAAO,IAAI,mBAAmB;GAC1B,SAAS;GACT,MAAM,WAAW,cAAc;GAC/B,QAAQ;GACR,UAAU;IACN,QAAQ;IACR,GAAG,oBAAoB,KAAK;IAC5B,UAAU;GACd;GACA,GAAG,uBAAuB,KAAK;EACnC,CAAC;CACL;;;;;;;;;;CAWA,OAAO,YACH,OAGkB;EAClB,OAAO,IAAI,mBAAmB;GAC1B,SAAS;GACT,MAAM,WAAW,cAAc;GAC/B,QAAQ;GACR,UAAU;IACN,QAAQ;IACR,GAAG,oBAAoB,KAAK;GAChC;GACA,GAAG,uBAAuB,KAAK;EACnC,CAAC;CACL;;;;;;;;CASA,OAAO,kBACH,OAGkB;EAClB,OAAO,IAAI,mBAAmB;GAC1B,SAAS;GACT,MAAM,WAAW,cAAc;GAC/B,QAAQ;GACR,UAAU;IACN,QAAQ;IACR,GAAG,oBAAoB,KAAK;GAChC;GACA,GAAG,uBAAuB,KAAK;EACnC,CAAC;CACL;;;;;;;;;CAUA,OAAO,WACH,OAGkB;EAClB,OAAO,IAAI,mBAAmB;GAC1B,SAAS;GACT,MAAM,WAAW,cAAc;GAC/B,QAAQ;GACR,UAAU;IAAE,QAAQ;IAAgB,GAAG,oBAAoB,KAAK;GAAE;GAClE,GAAG,uBAAuB,KAAK;EACnC,CAAC;CACL;AACJ;AAMA,SAAS,uBAAuB,SAAoC;CAChE,OAAO;EACH,OAAO,SAAS;EAChB,MAAM,SAAS;EACf,UAAU,SAAS;EACnB,eAAe,SAAS;EACxB,WAAW,SAAS;EACpB,WAAW,SAAS;EACpB,cAAc,SAAS;EACvB,eAAe,SAAS;CAC5B;AACJ;AAEA,SAAS,oBACL,OAC0C;CAC1C,MAAM,EACF,OACA,MACA,UACA,eACA,WACA,WACA,cACA,eACA,GAAG,aACH;CACJ,OAAO;AACX"}
+{"version":3,"file":"authorization-error.js","names":[],"sources":["../src/core/errors/utils/factory-helpers.ts","../src/core/errors/authorization-error.ts"],"sourcesContent":["// Shared helpers for the error factories: separating the AppError envelope\n// options from the free-form metadata, and dropping undefined-valued keys.\n// Previously each of authentication/authorization/integration carried its own\n// near-identical copy of these.\n\nimport type { AppErrorOptions } from \"../types.js\";\n\n/** The envelope fields AppError understands; everything else is metadata. */\nconst APP_ERROR_OPTION_KEYS = [\n    \"cause\",\n    \"type\",\n    \"severity\",\n    \"correlationId\",\n    \"requestId\",\n    \"commandId\",\n    \"createdAtIso\",\n    \"publicMessage\",\n] as const;\n\ntype AppErrorEnvelope = Pick<\n    AppErrorOptions,\n    (typeof APP_ERROR_OPTION_KEYS)[number]\n>;\n\n/**\n * Picks the AppError envelope fields out of a flat factory input, so they can\n * be forwarded to the constructor as options instead of leaking into metadata.\n */\nfunction pickAppErrorOptions(\n    input?: Partial<AppErrorOptions>,\n): AppErrorEnvelope {\n    return {\n        cause: input?.cause,\n        type: input?.type,\n        severity: input?.severity,\n        correlationId: input?.correlationId,\n        requestId: input?.requestId,\n        commandId: input?.commandId,\n        createdAtIso: input?.createdAtIso,\n        publicMessage: input?.publicMessage,\n    };\n}\n\n/**\n * The complement of {@link pickAppErrorOptions}: everything that is *not* an\n * AppError envelope field, i.e. the caller-supplied metadata. Keeps the cause\n * and the public message out of the internal data block.\n */\nfunction stripAppErrorOptions<T extends Record<string, unknown>>(\n    input: T,\n): Omit<T, (typeof APP_ERROR_OPTION_KEYS)[number]> {\n    const result = { ...input };\n    for (const key of APP_ERROR_OPTION_KEYS) {\n        delete result[key];\n    }\n    return result;\n}\n\n/** Drops keys whose value is `undefined` (mirrors how JSON.stringify treats them). */\nfunction compactMetadata<T extends Record<string, unknown>>(\n    input?: T,\n): T | undefined {\n    if (!input) return undefined;\n\n    return Object.fromEntries(\n        Object.entries(input).filter(([, value]) => value !== undefined),\n    ) as T;\n}\n\nexport { compactMetadata, pickAppErrorOptions, stripAppErrorOptions };\n","import { AppError } from \"./app-error.js\";\nimport { ErrorCodes } from \"./error-codes.js\";\nimport type { AppErrorOptions, ErrorSeverity } from \"./types.js\";\nimport { pickAppErrorOptions } from \"./utils/index.js\";\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Types\n// ─────────────────────────────────────────────────────────────────────────────\n\ntype AuthorizationErrorReason =\n    | \"forbidden\"\n    | \"missing_role\"\n    | \"missing_capability\"\n    | \"out_of_scope\"\n    | \"outside_time_window\"\n    | \"policy_denied\"\n    | \"unknown\";\n\ntype AuthorizationRequirement = {\n    role?: string;\n    capability?: string;\n    scope?: string; // e.g.: \"school:{id}\" or \"class:{id}\"\n};\n\ntype AuthorizationErrorMetadata = {\n    reason: AuthorizationErrorReason;\n\n    /** Stable action you evaluated (not an HTTP route — a \"business action\") */\n    action: string;\n\n    /** Resource identification (without leaking the full payload) */\n    resource?: { type: string; id?: string };\n\n    /**\n     * Optional: the acting principal (do not include sensitive data). `actorId`\n     * is the raw `RequestedBy` value — a user UUID *or* a `\"system:<job>\"`\n     * identity — so it must not be assumed to be a human user.\n     */\n    actor?: { actorId: string; role?: string };\n\n    /** Optional: expected requirement */\n    required?: AuthorizationRequirement;\n\n    /** Optional: policy (when you already have PolicyEvaluation or similar) */\n    policyId?: string;\n    policyVersion?: number;\n    evaluatedAtIso?: string;\n    decision?: \"allow\" | \"deny\";\n    reasonCode?: string;\n\n    /** Optional: additional non-sensitive info */\n    details?: string;\n};\n\n/**\n * Options for AuthorizationError factory methods.\n * Combines metadata fields (except 'reason') with common AppError options.\n */\ntype AuthorizationErrorFactoryOptions = Omit<\n    AuthorizationErrorMetadata,\n    \"reason\"\n> &\n    Omit<AppErrorOptions, \"metadata\">;\n\n// ─────────────────────────────────────────────────────────────────────────────\n// AuthorizationError\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Raised when an authenticated actor is not allowed to perform a business\n * action — the \"you may not\" error, distinct from authentication (\"who are\n * you\"). Maps to an HTTP 403 at the edge.\n *\n * The discriminating {@link reason} records *why* access was denied (a flat\n * forbid, a missing role/capability, an out-of-scope target, or a policy\n * decision) so the boundary can shape the response without re-deriving it. The\n * metadata is deliberately built around a stable business `action` and a\n * type/id resource reference rather than an HTTP route or full payload, keeping\n * sensitive data out of logs. Instances are frozen. Construct through the\n * static factories, never directly.\n */\nclass AuthorizationError extends AppError {\n    public readonly reason: AuthorizationErrorReason;\n\n    private constructor(params: {\n        message: string;\n        code: string;\n        reason: AuthorizationErrorReason;\n        metadata: AuthorizationErrorMetadata;\n        cause?: unknown;\n        type?: string;\n        severity?: ErrorSeverity;\n        correlationId?: string;\n        requestId?: string;\n        commandId?: string;\n        createdAtIso?: string;\n        publicMessage?: string;\n    }) {\n        super(params.message, params.code, {\n            cause: params.cause,\n            metadata: params.metadata,\n            type: params.type,\n            severity: params.severity,\n            correlationId: params.correlationId,\n            requestId: params.requestId,\n            commandId: params.commandId,\n            createdAtIso: params.createdAtIso,\n            publicMessage: params.publicMessage,\n        });\n\n        this.reason = params.reason;\n        Object.freeze(this);\n    }\n\n    // ─────────────────────────────────────────────────────────────────────────\n    // Factories\n    // ─────────────────────────────────────────────────────────────────────────\n\n    /**\n     * A flat denial with no more specific reason — the actor simply may not\n     * perform this action. Reach for a more precise factory\n     * ({@link AuthorizationError.missingCapability}, {@link AuthorizationError.outOfScope},\n     * {@link AuthorizationError.policyDenied}) when the cause is known.\n     */\n    static forbidden(\n        input: AuthorizationErrorFactoryOptions,\n    ): AuthorizationError {\n        return new AuthorizationError({\n            message: \"Action not allowed\",\n            code: ErrorCodes.authorization.forbidden,\n            reason: \"forbidden\",\n            metadata: { reason: \"forbidden\", ...extractMetadataOnly(input) },\n            ...pickAppErrorOptions(input),\n        });\n    }\n\n    /**\n     * The action was denied by an evaluated policy. Captures the deciding\n     * policy's id, version, and evaluation instant into the metadata (with\n     * `decision: \"deny\"`) so the denial is auditable back to the exact policy\n     * that produced it.\n     *\n     * @param input - Factory options plus the required `policyId`,\n     *   `policyVersion`, and `evaluatedAtIso` of the deciding policy.\n     */\n    static policyDenied(\n        input: AuthorizationErrorFactoryOptions & {\n            policyId: string;\n            policyVersion: number;\n            evaluatedAtIso: string;\n        },\n    ): AuthorizationError {\n        return new AuthorizationError({\n            message: \"Action denied by policy\",\n            code: ErrorCodes.authorization.policyDenied,\n            reason: \"policy_denied\",\n            metadata: {\n                reason: \"policy_denied\",\n                ...extractMetadataOnly(input),\n                decision: \"deny\",\n            },\n            ...pickAppErrorOptions(input),\n        });\n    }\n\n    /**\n     * The actor holds no role at all that bears on the action — the most basic\n     * denial, distinct from {@link AuthorizationError.missingCapability} (which\n     * means the actor *has* roles, just none granting the required capability).\n     * The expected {@link AuthorizationRequirement} is recorded so the boundary\n     * can tell the caller what grant is missing.\n     *\n     * @param input - Factory options plus the `required` role/capability/scope.\n     */\n    static missingRole(\n        input: AuthorizationErrorFactoryOptions & {\n            required: AuthorizationRequirement;\n        },\n    ): AuthorizationError {\n        return new AuthorizationError({\n            message: \"Missing required role to perform the action\",\n            code: ErrorCodes.authorization.missingRole,\n            reason: \"missing_role\",\n            metadata: {\n                reason: \"missing_role\",\n                ...extractMetadataOnly(input),\n            },\n            ...pickAppErrorOptions(input),\n        });\n    }\n\n    /**\n     * The actor lacks a required role or capability. The expected\n     * {@link AuthorizationRequirement} is recorded so the boundary can tell the\n     * caller precisely what grant is missing.\n     *\n     * @param input - Factory options plus the `required` role/capability/scope.\n     */\n    static missingCapability(\n        input: AuthorizationErrorFactoryOptions & {\n            required: AuthorizationRequirement;\n        },\n    ): AuthorizationError {\n        return new AuthorizationError({\n            message: \"Insufficient capability to perform the action\",\n            code: ErrorCodes.authorization.missingCapability,\n            reason: \"missing_capability\",\n            metadata: {\n                reason: \"missing_capability\",\n                ...extractMetadataOnly(input),\n            },\n            ...pickAppErrorOptions(input),\n        });\n    }\n\n    /**\n     * The actor may perform the action in general, but not on *this* target —\n     * the resource falls outside the actor's permitted scope (e.g. a different\n     * school or tenant than the one they are bound to).\n     *\n     * @param input - Factory options plus the optional `required` scope that the\n     *   target failed to satisfy.\n     */\n    static outOfScope(\n        input: AuthorizationErrorFactoryOptions & {\n            required?: AuthorizationRequirement;\n        },\n    ): AuthorizationError {\n        return new AuthorizationError({\n            message: \"Action outside the allowed scope\",\n            code: ErrorCodes.authorization.outOfScope,\n            reason: \"out_of_scope\",\n            metadata: { reason: \"out_of_scope\", ...extractMetadataOnly(input) },\n            ...pickAppErrorOptions(input),\n        });\n    }\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Helpers\n// ─────────────────────────────────────────────────────────────────────────────\n\nfunction extractMetadataOnly(\n    input: AuthorizationErrorFactoryOptions,\n): Omit<AuthorizationErrorMetadata, \"reason\"> {\n    const {\n        cause,\n        type,\n        severity,\n        correlationId,\n        requestId,\n        commandId,\n        createdAtIso,\n        publicMessage,\n        ...metadata\n    } = input;\n    return metadata;\n}\n\nexport { AuthorizationError };\nexport type {\n    AuthorizationErrorMetadata,\n    AuthorizationErrorReason,\n    AuthorizationRequirement,\n};\n"],"mappings":";;;AAQA,MAAM,wBAAwB;CAC1B;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACJ;;;;;AAWA,SAAS,oBACL,OACgB;CAChB,OAAO;EACH,OAAO,OAAO;EACd,MAAM,OAAO;EACb,UAAU,OAAO;EACjB,eAAe,OAAO;EACtB,WAAW,OAAO;EAClB,WAAW,OAAO;EAClB,cAAc,OAAO;EACrB,eAAe,OAAO;CAC1B;AACJ;;;;;;AAOA,SAAS,qBACL,OAC+C;CAC/C,MAAM,SAAS,EAAE,GAAG,MAAM;CAC1B,KAAK,MAAM,OAAO,uBACd,OAAO,OAAO;CAElB,OAAO;AACX;;AAGA,SAAS,gBACL,OACa;CACb,IAAI,CAAC,OAAO,OAAO,KAAA;CAEnB,OAAO,OAAO,YACV,OAAO,QAAQ,KAAK,EAAE,QAAQ,GAAG,WAAW,UAAU,KAAA,CAAS,CACnE;AACJ;;;;;;;;;;;;;;;;ACcA,IAAM,qBAAN,MAAM,2BAA2B,SAAS;CAGtC,YAAoB,QAajB;EACC,MAAM,OAAO,SAAS,OAAO,MAAM;GAC/B,OAAO,OAAO;GACd,UAAU,OAAO;GACjB,MAAM,OAAO;GACb,UAAU,OAAO;GACjB,eAAe,OAAO;GACtB,WAAW,OAAO;GAClB,WAAW,OAAO;GAClB,cAAc,OAAO;GACrB,eAAe,OAAO;EAC1B,CAAC;EAED,KAAK,SAAS,OAAO;EACrB,OAAO,OAAO,IAAI;CACtB;;;;;;;CAYA,OAAO,UACH,OACkB;EAClB,OAAO,IAAI,mBAAmB;GAC1B,SAAS;GACT,MAAM,WAAW,cAAc;GAC/B,QAAQ;GACR,UAAU;IAAE,QAAQ;IAAa,GAAG,oBAAoB,KAAK;GAAE;GAC/D,GAAG,oBAAoB,KAAK;EAChC,CAAC;CACL;;;;;;;;;;CAWA,OAAO,aACH,OAKkB;EAClB,OAAO,IAAI,mBAAmB;GAC1B,SAAS;GACT,MAAM,WAAW,cAAc;GAC/B,QAAQ;GACR,UAAU;IACN,QAAQ;IACR,GAAG,oBAAoB,KAAK;IAC5B,UAAU;GACd;GACA,GAAG,oBAAoB,KAAK;EAChC,CAAC;CACL;;;;;;;;;;CAWA,OAAO,YACH,OAGkB;EAClB,OAAO,IAAI,mBAAmB;GAC1B,SAAS;GACT,MAAM,WAAW,cAAc;GAC/B,QAAQ;GACR,UAAU;IACN,QAAQ;IACR,GAAG,oBAAoB,KAAK;GAChC;GACA,GAAG,oBAAoB,KAAK;EAChC,CAAC;CACL;;;;;;;;CASA,OAAO,kBACH,OAGkB;EAClB,OAAO,IAAI,mBAAmB;GAC1B,SAAS;GACT,MAAM,WAAW,cAAc;GAC/B,QAAQ;GACR,UAAU;IACN,QAAQ;IACR,GAAG,oBAAoB,KAAK;GAChC;GACA,GAAG,oBAAoB,KAAK;EAChC,CAAC;CACL;;;;;;;;;CAUA,OAAO,WACH,OAGkB;EAClB,OAAO,IAAI,mBAAmB;GAC1B,SAAS;GACT,MAAM,WAAW,cAAc;GAC/B,QAAQ;GACR,UAAU;IAAE,QAAQ;IAAgB,GAAG,oBAAoB,KAAK;GAAE;GAClE,GAAG,oBAAoB,KAAK;EAChC,CAAC;CACL;AACJ;AAMA,SAAS,oBACL,OAC0C;CAC1C,MAAM,EACF,OACA,MACA,UACA,eACA,WACA,WACA,cACA,eACA,GAAG,aACH;CACJ,OAAO;AACX"}

package/dist/authorizer.port.d.cts

@@ -68,7 +68,12 @@ type ScopeProps = {
  */
 declare class Scope extends ValueObject<ScopeProps, string> {
   private constructor();
-  /** Validates `"type:id"` or the global `"*"`, throwing on anything else. */
+  /**
+   * Validates `"type:id"` or the global `"*"`, throwing on anything else.
+   * `Scope.of("*")` is accepted and is equivalent to {@link Scope.global} —
+   * prefer `global()` at call-sites for intent, `of("*")` when rehydrating a
+   * stored string.
+   */
   static of(raw: string): Scope;
   /** The global scope `"*"`, which {@link includes} every other scope. */
   static global(): Scope;
@@ -101,12 +106,22 @@ interface AccessRequest {
    * Never a wildcard — only the *granted* permissions on roles may wildcard.
    */
   readonly required: Permission;
-  /** The target resource, identified without leaking its payload. */
+  /**
+   * The target resource, identified without leaking its payload. Carried for
+   * audit metadata only — the RBAC decisor does **not** check it. Per-resource
+   * ownership (this actor may cancel *this* order) is an ABAC/policy concern,
+   * not a role/permission one.
+   */
   readonly resource?: {
     readonly type: string;
     readonly id?: string;
   };
-  /** The scope the resource lives in, e.g. `Scope.of("school:123")`. */
+  /**
+   * The scope the resource lives in, e.g. `Scope.of("school:123")`. Asking in
+   * the global scope (`Scope.global()`) means "may I do this *everywhere*?" and
+   * so requires a globally-scoped grant — it is **not** "in any scope I happen
+   * to hold". Ask about a concrete scope to check a bounded grant.
+   */
   readonly scope: Scope;
 }
 //#endregion

package/dist/authorizer.port.d.ts

@@ -68,7 +68,12 @@ type ScopeProps = {
  */
 declare class Scope extends ValueObject<ScopeProps, string> {
   private constructor();
-  /** Validates `"type:id"` or the global `"*"`, throwing on anything else. */
+  /**
+   * Validates `"type:id"` or the global `"*"`, throwing on anything else.
+   * `Scope.of("*")` is accepted and is equivalent to {@link Scope.global} —
+   * prefer `global()` at call-sites for intent, `of("*")` when rehydrating a
+   * stored string.
+   */
   static of(raw: string): Scope;
   /** The global scope `"*"`, which {@link includes} every other scope. */
   static global(): Scope;
@@ -101,12 +106,22 @@ interface AccessRequest {
    * Never a wildcard — only the *granted* permissions on roles may wildcard.
    */
   readonly required: Permission;
-  /** The target resource, identified without leaking its payload. */
+  /**
+   * The target resource, identified without leaking its payload. Carried for
+   * audit metadata only — the RBAC decisor does **not** check it. Per-resource
+   * ownership (this actor may cancel *this* order) is an ABAC/policy concern,
+   * not a role/permission one.
+   */
   readonly resource?: {
     readonly type: string;
     readonly id?: string;
   };
-  /** The scope the resource lives in, e.g. `Scope.of("school:123")`. */
+  /**
+   * The scope the resource lives in, e.g. `Scope.of("school:123")`. Asking in
+   * the global scope (`Scope.global()`) means "may I do this *everywhere*?" and
+   * so requires a globally-scoped grant — it is **not** "in any scope I happen
+   * to hold". Ask about a concrete scope to check a bounded grant.
+   */
   readonly scope: Scope;
 }
 //#endregion

package/dist/composite-authorizer.d.cts

@@ -1,7 +1,7 @@
 import { t as RequestedBy } from "./requested-by.cjs";
 import { t as AuthorizationError } from "./authorization-error.cjs";
 import { r as Result } from "./result.cjs";
-import { T as PolicyContext, j as ConditionNode, t as CoreConfig } from "./core-config.cjs";
+import { A as ConditionNode, t as CoreConfig, w as PolicyContext } from "./core-config.cjs";
 import { t as ValueObject } from "./value-object.cjs";
 import { n as AccessRequest, t as AuthorizerPort } from "./authorizer.port.cjs";
 
@@ -93,6 +93,26 @@ type AbacRuleProps = {
  * 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.
  */
 declare class AbacRule extends ValueObject<AbacRuleProps, AbacRuleProps> {
   private constructor();
@@ -128,28 +148,51 @@ type CombiningAlgorithm = "deny-overrides" | "permit-overrides" | "first-applica
 /** The resolved decision plus the rule (if any) that produced it. */
 //#endregion
 //#region src/core/abac/domain/policy-set.d.ts
+/**
+ * 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.
+ */
+type OnEvaluationError = "fail-closed" | "skip-rule";
 /**
  * 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}.
  */
 declare class AbacPolicySet {
   private readonly _rules;
   private readonly _algorithm;
   private readonly _defaultEffect;
+  private readonly _onEvaluationError;
   private constructor();
+  /**
+   * 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;
+  private static assertUniqueIds;
   get rules(): readonly AbacRule[];
   get algorithm(): CombiningAlgorithm;
   get defaultEffect(): RuleEffect;
+  get onEvaluationError(): OnEvaluationError;
 }
 //#endregion
 //#region src/core/abac/authorizer.d.ts
@@ -173,17 +216,27 @@ 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.
  */
 declare class AbacAuthorizer {
   private readonly coreConfig;
+  private readonly clock;
   constructor(params?: {
     readonly coreConfig?: CoreConfig;
+    /** Injectable clock for deterministic timestamps; defaults to `() => new Date()`. */
+    readonly clock?: () => Date;
   });
   authorize(request: AbacRequest, policies: AbacPolicySet): Result<AbacDecision, AuthorizationError>;
+  private reportDecision;
 }
 //#endregion
 //#region src/core/abac/composite-authorizer.d.ts
@@ -212,5 +265,5 @@ declare class CompositeAuthorizer {
   authorize(request: CompositeAccessRequest): Promise<Result<void, AuthorizationError>>;
 }
 //#endregion
-export { AbacPolicySet as a, AbacRuleProps as c, AbacAuthorizerPort as d, AbacAttributes as f, AbacDecision as i, RuleEffect as l, CompositeAuthorizer as n, CombiningAlgorithm as o, AbacRequest as p, AbacAuthorizer as r, AbacRule as s, CompositeAccessRequest as t, abacContext as u };
+export { AbacPolicySet as a, AbacRule as c, abacContext as d, AbacAuthorizerPort as f, AbacDecision as i, AbacRuleProps as l, AbacRequest as m, CompositeAuthorizer as n, OnEvaluationError as o, AbacAttributes as p, AbacAuthorizer as r, CombiningAlgorithm as s, CompositeAccessRequest as t, RuleEffect as u };
 //# sourceMappingURL=composite-authorizer.d.cts.map

package/dist/composite-authorizer.d.ts

@@ -1,7 +1,7 @@
 import { t as RequestedBy } from "./requested-by.js";
 import { t as AuthorizationError } from "./authorization-error.js";
 import { r as Result } from "./result.js";
-import { T as PolicyContext, j as ConditionNode, t as CoreConfig } from "./core-config.js";
+import { A as ConditionNode, t as CoreConfig, w as PolicyContext } from "./core-config.js";
 import { t as ValueObject } from "./value-object.js";
 import { n as AccessRequest, t as AuthorizerPort } from "./authorizer.port.js";
 
@@ -93,6 +93,26 @@ type AbacRuleProps = {
  * 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.
  */
 declare class AbacRule extends ValueObject<AbacRuleProps, AbacRuleProps> {
   private constructor();
@@ -128,28 +148,51 @@ type CombiningAlgorithm = "deny-overrides" | "permit-overrides" | "first-applica
 /** The resolved decision plus the rule (if any) that produced it. */
 //#endregion
 //#region src/core/abac/domain/policy-set.d.ts
+/**
+ * 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.
+ */
+type OnEvaluationError = "fail-closed" | "skip-rule";
 /**
  * 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}.
  */
 declare class AbacPolicySet {
   private readonly _rules;
   private readonly _algorithm;
   private readonly _defaultEffect;
+  private readonly _onEvaluationError;
   private constructor();
+  /**
+   * 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;
+  private static assertUniqueIds;
   get rules(): readonly AbacRule[];
   get algorithm(): CombiningAlgorithm;
   get defaultEffect(): RuleEffect;
+  get onEvaluationError(): OnEvaluationError;
 }
 //#endregion
 //#region src/core/abac/authorizer.d.ts
@@ -173,17 +216,27 @@ 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.
  */
 declare class AbacAuthorizer {
   private readonly coreConfig;
+  private readonly clock;
   constructor(params?: {
     readonly coreConfig?: CoreConfig;
+    /** Injectable clock for deterministic timestamps; defaults to `() => new Date()`. */
+    readonly clock?: () => Date;
   });
   authorize(request: AbacRequest, policies: AbacPolicySet): Result<AbacDecision, AuthorizationError>;
+  private reportDecision;
 }
 //#endregion
 //#region src/core/abac/composite-authorizer.d.ts
@@ -212,5 +265,5 @@ declare class CompositeAuthorizer {
   authorize(request: CompositeAccessRequest): Promise<Result<void, AuthorizationError>>;
 }
 //#endregion
-export { AbacPolicySet as a, AbacRuleProps as c, AbacAuthorizerPort as d, AbacAttributes as f, AbacDecision as i, RuleEffect as l, CompositeAuthorizer as n, CombiningAlgorithm as o, AbacRequest as p, AbacAuthorizer as r, AbacRule as s, CompositeAccessRequest as t, abacContext as u };
+export { AbacPolicySet as a, AbacRule as c, abacContext as d, AbacAuthorizerPort as f, AbacDecision as i, AbacRuleProps as l, AbacRequest as m, CompositeAuthorizer as n, OnEvaluationError as o, AbacAttributes as p, AbacAuthorizer as r, CombiningAlgorithm as s, CompositeAccessRequest as t, RuleEffect as u };
 //# sourceMappingURL=composite-authorizer.d.ts.map