@cullet/erp-core 1.2.0 → 1.4.0

package/dist/rule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule.js","names":[],"sources":["../src/core/abac/attributes.ts","../src/core/abac/combining.ts","../src/core/abac/authorizer.ts","../src/core/abac/composite-authorizer.ts","../src/core/abac/domain/policy-set.ts","../src/core/abac/domain/rule.ts"],"sourcesContent":["import type { PolicyContext } from \"../policies/engines/gate-types.js\";\n\nimport type { AbacRequest } from \"./abac-request.js\";\n\n/**\n * Flattens an {@link AbacRequest} into the nested {@link PolicyContext} the\n * condition evaluator reads (it resolves dotted fields like `resource.status` by\n * walking nested objects). The actor lands as `subject.id`; the four attribute\n * bags nest under `subject` / `resource` / `action` / `env`; a `resource`\n * reference adds `resource.type` / `resource.id`. The actor id and the resource\n * reference win over any same-named keys in the attribute bags.\n *\n * Consumers fold dynamic facts (e.g. RBAC roles/permissions derived from grants,\n * or a computed `ownerIsActor` flag) into `attributes.subject` / `resource` so\n * rules can reference `subject.roles`, `resource.ownerIsActor`, and the like.\n */\nexport function abacContext(request: AbacRequest): PolicyContext {\n    const attributes = request.attributes;\n\n    const subject: Record<string, unknown> = {\n        ...attributes.subject,\n        id: request.actor.raw,\n    };\n\n    const resource: Record<string, unknown> = { ...attributes.resource };\n    if (request.resource) {\n        resource.type = request.resource.type;\n        if (request.resource.id !== undefined) {\n            resource.id = request.resource.id;\n        }\n    }\n\n    return {\n        subject,\n        resource,\n        action: { ...attributes.action },\n        env: { ...attributes.environment },\n    };\n}\n","import type { AbacRule, RuleEffect } from \"./domain/rule.js\";\n\n/**\n * How an {@link AbacPolicySet} resolves several applicable rules into one effect.\n *\n * - `deny-overrides` (default, secure): any applicable DENY wins; otherwise the\n *   first PERMIT; otherwise the set's default effect.\n * - `permit-overrides`: any applicable PERMIT wins; otherwise the first DENY;\n *   otherwise the default effect.\n * - `first-applicable`: the effect of the first rule that matches; otherwise the\n *   default effect.\n */\nexport type CombiningAlgorithm =\n    | \"deny-overrides\"\n    | \"permit-overrides\"\n    | \"first-applicable\";\n\n/** The resolved decision plus the rule (if any) that produced it. */\nexport interface CombineResult {\n    readonly effect: RuleEffect;\n    readonly decidingRule?: AbacRule;\n}\n\nfunction firstWithEffect(\n    rules: readonly AbacRule[],\n    effect: RuleEffect,\n): AbacRule | undefined {\n    return rules.find((rule) => rule.effect === effect);\n}\n\n/**\n * Applies `algorithm` to the already-matched `applicable` rules, falling back to\n * `defaultEffect` when the algorithm reaches no rule-backed decision. Pure and\n * total; the returned `decidingRule` is absent exactly when `defaultEffect` was\n * used.\n */\nexport function combine(\n    algorithm: CombiningAlgorithm,\n    applicable: readonly AbacRule[],\n    defaultEffect: RuleEffect,\n): CombineResult {\n    switch (algorithm) {\n        case \"deny-overrides\": {\n            const deny = firstWithEffect(applicable, \"DENY\");\n            if (deny) return { effect: \"DENY\", decidingRule: deny };\n            const permit = firstWithEffect(applicable, \"PERMIT\");\n            if (permit) return { effect: \"PERMIT\", decidingRule: permit };\n            return { effect: defaultEffect };\n        }\n        case \"permit-overrides\": {\n            const permit = firstWithEffect(applicable, \"PERMIT\");\n            if (permit) return { effect: \"PERMIT\", decidingRule: permit };\n            const deny = firstWithEffect(applicable, \"DENY\");\n            if (deny) return { effect: \"DENY\", decidingRule: deny };\n            return { effect: defaultEffect };\n        }\n        case \"first-applicable\": {\n            const first = applicable[0];\n            if (first) return { effect: first.effect, decidingRule: first };\n            return { effect: defaultEffect };\n        }\n    }\n}\n","import { type CoreConfig, coreConfig } from \"../config/index.js\";\nimport { AuthorizationError } from \"../errors/authorization-error.js\";\nimport { ConditionEvaluatorV1 } from \"../policies/engines/v1/condition-evaluator.js\";\nimport { Result } from \"../result/result.js\";\n\nimport type { AbacRequest } from \"./abac-request.js\";\nimport { abacContext } from \"./attributes.js\";\nimport { combine, type CombiningAlgorithm } from \"./combining.js\";\nimport type { AbacPolicySet } from \"./domain/policy-set.js\";\nimport type { AbacRule } from \"./domain/rule.js\";\n\n// ABAC reuses the gate engine's v1 condition matcher; the version stamps the\n// evaluation reports the shared reporter emits.\nconst ENGINE_VERSION = 1;\n\n/** The successful decision returned by {@link AbacAuthorizer.authorize}. */\ninterface AbacDecision {\n    /** The audited business action that was allowed. */\n    readonly action: string;\n    readonly effect: \"PERMIT\";\n    /** The id of the rule that permitted, or `\"<default>\"` when the set's default did. */\n    readonly matchedRule: string;\n    readonly algorithm: CombiningAlgorithm;\n    /** When the decision was made, ISO-8601. */\n    readonly grantedAtIso: string;\n}\n\n/**\n * The pure ABAC decisor. Given an {@link AbacRequest} and an\n * {@link AbacPolicySet}, it flattens the request's attributes into a context,\n * matches each rule's condition with the gate engine's pure condition evaluator\n * (reused, not reimplemented), resolves the effects through the set's combining\n * algorithm, and returns a {@link Result} — never throwing, mirroring the\n * \"errors as values\" contract of `RbacAuthorizer`/`GateEngineV1`.\n *\n * A denial maps to {@link AuthorizationError.policyDenied}, attributed to the\n * deciding rule's `id`/`version`; a condition-evaluation failure (a missing\n * attribute, a wrong-typed operand) fails closed as\n * {@link AuthorizationError.forbidden}. Loading the dynamic attributes is the\n * consumer's job (behind an `AbacAuthorizerPort` adapter); this class only decides.\n */\nclass AbacAuthorizer {\n    private readonly coreConfig: CoreConfig;\n\n    constructor(params: { readonly coreConfig?: CoreConfig } = {}) {\n        this.coreConfig = params.coreConfig ?? coreConfig;\n    }\n\n    authorize(\n        request: AbacRequest,\n        policies: AbacPolicySet,\n    ): Result<AbacDecision, AuthorizationError> {\n        const context = abacContext(request);\n        const evaluator = new ConditionEvaluatorV1(\n            context,\n            this.coreConfig.getConditionEvaluationOptions(ENGINE_VERSION),\n        );\n\n        const applicable: AbacRule[] = [];\n        for (const rule of policies.rules) {\n            const matched = evaluator.evaluate(rule.condition);\n            if (matched.isErr()) {\n                // Fail closed: a technical evaluation error is never a silent PERMIT.\n                return Result.err(\n                    AuthorizationError.forbidden({\n                        action: request.action,\n                        resource: request.resource,\n                        actor: { userId: request.actor.raw },\n                        details: matched.errorOrNull() ?? undefined,\n                    }),\n                );\n            }\n            if (matched.getOrThrow()) {\n                applicable.push(rule);\n            }\n        }\n\n        const { effect, decidingRule } = combine(\n            policies.algorithm,\n            applicable,\n            policies.defaultEffect,\n        );\n\n        if (effect === \"PERMIT\") {\n            return Result.ok({\n                action: request.action,\n                effect: \"PERMIT\",\n                matchedRule: decidingRule?.id ?? \"<default>\",\n                algorithm: policies.algorithm,\n                grantedAtIso: new Date().toISOString(),\n            });\n        }\n\n        return Result.err(\n            AuthorizationError.policyDenied({\n                policyId: decidingRule?.id ?? \"<default-deny>\",\n                policyVersion: decidingRule?.version ?? 0,\n                evaluatedAtIso: new Date().toISOString(),\n                action: request.action,\n                resource: request.resource,\n                actor: { userId: request.actor.raw },\n                reasonCode: decidingRule?.id,\n            }),\n        );\n    }\n}\n\nexport { AbacAuthorizer, type AbacDecision };\n","import { Result } from \"../result/result.js\";\nimport type { AbacAuthorizerPort } from \"../application/ports/abac-authorizer.port.js\";\nimport type { AuthorizerPort } from \"../application/ports/authorizer.port.js\";\nimport type { AuthorizationError } from \"../errors/authorization-error.js\";\nimport type { AccessRequest } from \"../rbac/access-request.js\";\n\nimport type { AbacAttributes } from \"./abac-request.js\";\n\n/**\n * The request a {@link CompositeAuthorizer} accepts — one object that satisfies\n * both the RBAC {@link AccessRequest} (its `required`/`scope`) and the ABAC\n * request (its `attributes`).\n */\ntype CompositeAccessRequest = AccessRequest & {\n    readonly attributes: AbacAttributes;\n};\n\n/**\n * Runs a coarse RBAC check first, then refines with ABAC — the standard hybrid\n * \"does the actor hold the capability, *and* do the attributes allow it here?\"\n * flow. Short-circuits with the RBAC denial when the actor is not even capable,\n * so the boundary sees the most specific 403.\n *\n * Only the two port interfaces are referenced (both erased at runtime), so this\n * pulls in no RBAC/ABAC engine code of its own — it just sequences the seams the\n * consumer wires up.\n */\nclass CompositeAuthorizer {\n    constructor(\n        private readonly rbac: AuthorizerPort,\n        private readonly abac: AbacAuthorizerPort,\n    ) {}\n\n    async authorize(\n        request: CompositeAccessRequest,\n    ): Promise<Result<void, AuthorizationError>> {\n        const coarse = await this.rbac.authorize(request);\n        if (coarse.isErr()) {\n            return coarse;\n        }\n        return this.abac.authorize(request);\n    }\n}\n\nexport { CompositeAuthorizer, type CompositeAccessRequest };\n","import type { CombiningAlgorithm } from \"../combining.js\";\n\nimport type { AbacRule, RuleEffect } from \"./rule.js\";\n\n/**\n * An ordered collection of {@link AbacRule}s plus how to combine them\n * ({@link CombiningAlgorithm}) and what to decide when no rule applies\n * ({@link defaultEffect}). This is where ABAC goes beyond a single gate\n * condition: several PERMIT/DENY rules resolved by an explicit algorithm.\n *\n * Closed by default — the combining algorithm defaults to `\"deny-overrides\"` and\n * the default effect to `\"DENY\"`, so a request matching nothing is denied. A\n * plain holder (not a value object); build through {@link of}.\n */\nclass AbacPolicySet {\n    private constructor(\n        private readonly _rules: readonly AbacRule[],\n        private readonly _algorithm: CombiningAlgorithm,\n        private readonly _defaultEffect: RuleEffect,\n    ) {\n        Object.freeze(this._rules);\n        Object.freeze(this);\n    }\n\n    static of(\n        rules: readonly AbacRule[],\n        options: {\n            readonly algorithm?: CombiningAlgorithm;\n            readonly defaultEffect?: RuleEffect;\n        } = {},\n    ): AbacPolicySet {\n        return new AbacPolicySet(\n            [...rules],\n            options.algorithm ?? \"deny-overrides\",\n            options.defaultEffect ?? \"DENY\",\n        );\n    }\n\n    get rules(): readonly AbacRule[] {\n        return this._rules;\n    }\n\n    get algorithm(): CombiningAlgorithm {\n        return this._algorithm;\n    }\n\n    get defaultEffect(): RuleEffect {\n        return this._defaultEffect;\n    }\n}\n\nexport { AbacPolicySet };\n","import { ValidationCode } from \"../../exceptions/validation-code.js\";\nimport { InvalidValueException } from \"../../exceptions/validation-exception.js\";\nimport { ValidationField } from \"../../exceptions/validation-field.js\";\nimport { ValueObject } from \"../../domain/value-object.js\";\nimport type {\n    ConditionNode,\n    ConditionOp,\n} from \"../../policies/engines/v1/condition-types.js\";\n\n/** Whether a matching {@link AbacRule} permits or denies the action. */\ntype RuleEffect = \"PERMIT\" | \"DENY\";\n\n/**\n * The serializable shape of a rule: a stable `id`/`version` (surfaced on a\n * denial as `policyId`/`policyVersion`), the {@link RuleEffect}, and the\n * {@link ConditionNode} that decides whether the rule applies to a request's\n * flattened attributes.\n */\ntype AbacRuleProps = {\n    readonly id: string;\n    readonly version: number;\n    readonly effect: RuleEffect;\n    readonly condition: ConditionNode;\n    readonly description?: string;\n};\n\nconst RULE_FIELD = ValidationField.of(\"abacRule\");\n\nconst CONDITION_OPS = new Set<ConditionOp>([\n    \"eq\",\n    \"neq\",\n    \"gt\",\n    \"gte\",\n    \"lt\",\n    \"lte\",\n    \"in\",\n    \"notIn\",\n    \"isNull\",\n    \"isNotNull\",\n]);\n\nconst RULE_EFFECTS = new Set<RuleEffect>([\"PERMIT\", \"DENY\"]);\n\nfunction isPlainObject(value: unknown): value is Record<string, unknown> {\n    return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\n/**\n * A single attribute-based rule: an {@link RuleEffect} that takes hold when its\n * {@link ConditionNode} matches the request's flattened attributes. The\n * condition reuses the gate/compute condition DSL (`{ field, op, value }` leaves\n * combined with `and`/`or`/`not`), so a consumer learns one condition language\n * across the whole kit.\n *\n * A zod-free value object: it validates its own shape on construction (throwing\n * {@link InvalidValueException}) and is deep-frozen thereafter. Because rules are\n * authored in TypeScript — trusted data, not untrusted JSON — the structural\n * check is a hand-rolled walk of the condition tree rather than a schema parse.\n * Build one through {@link of}; the constructor is private.\n */\nclass AbacRule extends ValueObject<AbacRuleProps, AbacRuleProps> {\n    private constructor(props: AbacRuleProps) {\n        super(props);\n        this.finalize();\n    }\n\n    /**\n     * Builds a rule, validating that `id` is non-blank, `version` is an integer\n     * ≥ 1, `effect` is `\"PERMIT\"`/`\"DENY\"`, and `condition` is a well-formed\n     * condition node. Throws {@link InvalidValueException} otherwise.\n     */\n    static of(props: AbacRuleProps): AbacRule {\n        if (typeof props.id !== \"string\" || props.id.trim().length === 0) {\n            throw new InvalidValueException(\n                RULE_FIELD.nested(\"id\"),\n                ValidationCode.BLANK,\n                `abac rule id must be a non-empty string, got \"${props.id}\"`,\n            );\n        }\n\n        if (!Number.isInteger(props.version) || props.version < 1) {\n            throw new InvalidValueException(\n                RULE_FIELD.nested(\"version\"),\n                ValidationCode.OUT_OF_RANGE,\n                `abac rule version must be an integer >= 1, got \"${props.version}\"`,\n            );\n        }\n\n        if (!RULE_EFFECTS.has(props.effect)) {\n            throw new InvalidValueException(\n                RULE_FIELD.nested(\"effect\"),\n                ValidationCode.INVALID_FORMAT,\n                `abac rule effect must be \"PERMIT\" or \"DENY\", got \"${String(props.effect)}\"`,\n            );\n        }\n\n        AbacRule.assertConditionShape(props.condition);\n\n        return new AbacRule(props);\n    }\n\n    // Mirrors what the shared condition evaluator would reject at eval time\n    // (empty and/or nodes, malformed leaves) but fails fast at construction.\n    private static assertConditionShape(node: unknown): void {\n        if (!isPlainObject(node)) {\n            AbacRule.rejectCondition(\n                \"abac rule condition must be a leaf { field, op } or an { and | or | not } node\",\n            );\n        }\n\n        if (\"and\" in node || \"or\" in node) {\n            const key = \"and\" in node ? \"and\" : \"or\";\n            const children = node[key];\n            if (!Array.isArray(children) || children.length === 0) {\n                AbacRule.rejectCondition(\n                    `abac rule \"${key}\" node must hold a non-empty array of child conditions`,\n                );\n            }\n            for (const child of children) {\n                AbacRule.assertConditionShape(child);\n            }\n            return;\n        }\n\n        if (\"not\" in node) {\n            AbacRule.assertConditionShape(node.not);\n            return;\n        }\n\n        if (\"field\" in node && \"op\" in node) {\n            if (\n                typeof node.field !== \"string\" ||\n                node.field.trim().length === 0\n            ) {\n                AbacRule.rejectCondition(\n                    `abac rule condition leaf \"field\" must be a non-empty string, got \"${String(node.field)}\"`,\n                );\n            }\n            if (\n                typeof node.op !== \"string\" ||\n                !CONDITION_OPS.has(node.op as ConditionOp)\n            ) {\n                AbacRule.rejectCondition(\n                    `abac rule condition leaf \"op\" is not a supported operator, got \"${String(node.op)}\"`,\n                );\n            }\n            return;\n        }\n\n        AbacRule.rejectCondition(\n            \"abac rule condition must be a leaf { field, op } or an { and | or | not } node\",\n        );\n    }\n\n    private static rejectCondition(message: string): never {\n        throw new InvalidValueException(\n            RULE_FIELD.nested(\"condition\"),\n            ValidationCode.INVALID_FORMAT,\n            message,\n        );\n    }\n\n    get id(): string {\n        return this.value.id;\n    }\n\n    get version(): number {\n        return this.value.version;\n    }\n\n    get effect(): RuleEffect {\n        return this.value.effect;\n    }\n\n    /** The condition tree evaluated against a request's flattened attributes. */\n    get condition(): ConditionNode {\n        return this.value.condition as ConditionNode;\n    }\n\n    get description(): string | undefined {\n        return this.value.description;\n    }\n\n    toPrimitive(): AbacRuleProps {\n        return {\n            id: this.value.id,\n            version: this.value.version,\n            effect: this.value.effect,\n            condition: this.value.condition as ConditionNode,\n            ...(this.value.description !== undefined\n                ? { description: this.value.description }\n                : {}),\n        };\n    }\n}\n\nexport { AbacRule, type AbacRuleProps, type RuleEffect };\n"],"mappings":"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"}

package/dist/ruleset-registry.cjs

@@ -0,0 +1,47 @@
+const require_domain_exception = require("./domain-exception.cjs");
+//#region src/core/domain/rulesets/ruleset-registry.ts
+var RulesetRegistryError = class extends require_domain_exception.DomainException {};
+function parseVersion(id) {
+	const atIdx = id.lastIndexOf("@");
+	const [major, minor] = id.slice(atIdx + 1).split(".").map(Number);
+	return [major, minor];
+}
+var RulesetRegistry = class {
+	constructor() {
+		this._store = /* @__PURE__ */ new Map();
+		this._sealed = false;
+	}
+	register(ruleset) {
+		if (this._sealed) throw new RulesetRegistryError("Registry is sealed. No new rulesets can be registered.");
+		if (this._store.has(ruleset.id)) throw new RulesetRegistryError(`Ruleset with id "${ruleset.id}" is already registered.`);
+		this._store.set(ruleset.id, ruleset);
+	}
+	seal() {
+		this._sealed = true;
+	}
+	get(id) {
+		const ruleset = this._store.get(id);
+		if (!ruleset) throw new RulesetRegistryError(`Ruleset "${id}" not found. Available: [${Array.from(this._store.keys()).join(", ")}]`);
+		return ruleset;
+	}
+	getCurrent(prefix) {
+		const matchingEntries = Array.from(this._store.entries()).filter(([key]) => key.startsWith(prefix + "@"));
+		if (matchingEntries.length === 0) throw new RulesetRegistryError(`No rulesets found with prefix "${prefix}".`);
+		const sorted = matchingEntries.sort(([a], [b]) => {
+			const [aMajor, aMinor] = parseVersion(a);
+			const [bMajor, bMinor] = parseVersion(b);
+			if (aMajor !== bMajor) return aMajor - bMajor;
+			return aMinor - bMinor;
+		});
+		return sorted[sorted.length - 1][1];
+	}
+};
+//#endregion
+Object.defineProperty(exports, "RulesetRegistry", {
+	enumerable: true,
+	get: function() {
+		return RulesetRegistry;
+	}
+});
+
+//# sourceMappingURL=ruleset-registry.cjs.map

package/dist/ruleset-registry.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ruleset-registry.cjs","names":["DomainException"],"sources":["../src/core/domain/rulesets/ruleset-registry.ts"],"sourcesContent":["import { DomainException } from \"../../exceptions/domain-exception.js\";\nimport {\n    type Ruleset,\n    type RulesetRegistry as RulesetRegistryContract,\n} from \"./ruleset.contracts.js\";\n\nclass RulesetRegistryError extends DomainException {}\n\nfunction parseVersion(id: string): [number, number] {\n    const atIdx = id.lastIndexOf(\"@\");\n    const versionStr = id.slice(atIdx + 1);\n    const [major, minor] = versionStr.split(\".\").map(Number);\n    return [major, minor];\n}\n\nclass RulesetRegistry implements RulesetRegistryContract {\n    private readonly _store = new Map<string, Ruleset>();\n    private _sealed = false;\n\n    register(ruleset: Ruleset): void {\n        if (this._sealed) {\n            throw new RulesetRegistryError(\n                \"Registry is sealed. No new rulesets can be registered.\",\n            );\n        }\n        if (this._store.has(ruleset.id)) {\n            throw new RulesetRegistryError(\n                `Ruleset with id \"${ruleset.id}\" is already registered.`,\n            );\n        }\n        this._store.set(ruleset.id, ruleset);\n    }\n\n    seal(): void {\n        this._sealed = true;\n    }\n\n    get<T extends Ruleset>(id: string): T {\n        const ruleset = this._store.get(id);\n        if (!ruleset) {\n            const available = Array.from(this._store.keys()).join(\", \");\n            throw new RulesetRegistryError(\n                `Ruleset \"${id}\" not found. Available: [${available}]`,\n            );\n        }\n        return ruleset as T;\n    }\n\n    getCurrent<T extends Ruleset>(prefix: string): T {\n        const matchingEntries = Array.from(this._store.entries()).filter(\n            ([key]) => key.startsWith(prefix + \"@\"),\n        );\n\n        if (matchingEntries.length === 0) {\n            throw new RulesetRegistryError(\n                `No rulesets found with prefix \"${prefix}\".`,\n            );\n        }\n\n        const sorted = matchingEntries.sort(([a], [b]) => {\n            const [aMajor, aMinor] = parseVersion(a);\n            const [bMajor, bMinor] = parseVersion(b);\n            if (aMajor !== bMajor) return aMajor - bMajor;\n            return aMinor - bMinor;\n        });\n\n        return sorted[sorted.length - 1][1] as T;\n    }\n}\n\nexport { RulesetRegistry };\n"],"mappings":";;AAMA,IAAM,uBAAN,cAAmCA,yBAAAA,gBAAgB,CAAC;AAEpD,SAAS,aAAa,IAA8B;CAChD,MAAM,QAAQ,GAAG,YAAY,GAAG;CAEhC,MAAM,CAAC,OAAO,SADK,GAAG,MAAM,QAAQ,CACJ,EAAE,MAAM,GAAG,EAAE,IAAI,MAAM;CACvD,OAAO,CAAC,OAAO,KAAK;AACxB;AAEA,IAAM,kBAAN,MAAyD;;gCAC3B,IAAI,IAAqB;iBACjC;;CAElB,SAAS,SAAwB;EAC7B,IAAI,KAAK,SACL,MAAM,IAAI,qBACN,wDACJ;EAEJ,IAAI,KAAK,OAAO,IAAI,QAAQ,EAAE,GAC1B,MAAM,IAAI,qBACN,oBAAoB,QAAQ,GAAG,yBACnC;EAEJ,KAAK,OAAO,IAAI,QAAQ,IAAI,OAAO;CACvC;CAEA,OAAa;EACT,KAAK,UAAU;CACnB;CAEA,IAAuB,IAAe;EAClC,MAAM,UAAU,KAAK,OAAO,IAAI,EAAE;EAClC,IAAI,CAAC,SAED,MAAM,IAAI,qBACN,YAAY,GAAG,2BAFD,MAAM,KAAK,KAAK,OAAO,KAAK,CAAC,EAAE,KAAK,IAEA,EAAE,EACxD;EAEJ,OAAO;CACX;CAEA,WAA8B,QAAmB;EAC7C,MAAM,kBAAkB,MAAM,KAAK,KAAK,OAAO,QAAQ,CAAC,EAAE,QACrD,CAAC,SAAS,IAAI,WAAW,SAAS,GAAG,CAC1C;EAEA,IAAI,gBAAgB,WAAW,GAC3B,MAAM,IAAI,qBACN,kCAAkC,OAAO,GAC7C;EAGJ,MAAM,SAAS,gBAAgB,MAAM,CAAC,IAAI,CAAC,OAAO;GAC9C,MAAM,CAAC,QAAQ,UAAU,aAAa,CAAC;GACvC,MAAM,CAAC,QAAQ,UAAU,aAAa,CAAC;GACvC,IAAI,WAAW,QAAQ,OAAO,SAAS;GACvC,OAAO,SAAS;EACpB,CAAC;EAED,OAAO,OAAO,OAAO,SAAS,GAAG;CACrC;AACJ"}

package/dist/rulesets/index.cjs

@@ -0,0 +1,3 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_ruleset_registry = require("../ruleset-registry.cjs");
+exports.RulesetRegistry = require_ruleset_registry.RulesetRegistry;

package/dist/rulesets/index.d.cts

@@ -0,0 +1,2 @@
+import { a as Ruleset, i as InvariantRuleset, n as RulesetRegistry, o as RulesetId, r as CreationRuleset, t as ValueObjectRuleset } from "../value-object-ruleset.contracts.cjs";
+export { CreationRuleset, InvariantRuleset, Ruleset, RulesetId, RulesetRegistry, ValueObjectRuleset };

package/dist/temporal-guards.cjs

@@ -0,0 +1,32 @@
+const require_invariant_violation_exception = require("./invariant-violation-exception.cjs");
+//#region src/core/shared/temporal-guards.ts
+function isValidDate(value) {
+	return value instanceof Date && !Number.isNaN(value.getTime());
+}
+function cloneDate(date) {
+	return new Date(date.getTime());
+}
+function assertValidDate(fieldName, value) {
+	if (!isValidDate(value)) throw new require_invariant_violation_exception.InvariantViolationException(`${fieldName} must be a valid Date instance`);
+}
+//#endregion
+Object.defineProperty(exports, "assertValidDate", {
+	enumerable: true,
+	get: function() {
+		return assertValidDate;
+	}
+});
+Object.defineProperty(exports, "cloneDate", {
+	enumerable: true,
+	get: function() {
+		return cloneDate;
+	}
+});
+Object.defineProperty(exports, "isValidDate", {
+	enumerable: true,
+	get: function() {
+		return isValidDate;
+	}
+});
+
+//# sourceMappingURL=temporal-guards.cjs.map

package/dist/temporal-guards.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"temporal-guards.cjs","names":["InvariantViolationException"],"sources":["../src/core/shared/temporal-guards.ts"],"sourcesContent":["import { InvariantViolationException } from \"../exceptions/invariant-violation-exception.js\";\n\nfunction isValidDate(value: unknown): value is Date {\n    return value instanceof Date && !Number.isNaN(value.getTime());\n}\n\nfunction cloneDate(date: Date): Date {\n    return new Date(date.getTime());\n}\n\nfunction assertValidDate(\n    fieldName: string,\n    value: unknown,\n): asserts value is Date {\n    if (!isValidDate(value)) {\n        throw new InvariantViolationException(\n            `${fieldName} must be a valid Date instance`,\n        );\n    }\n}\n\nexport { assertValidDate, cloneDate, isValidDate };\n"],"mappings":";;AAEA,SAAS,YAAY,OAA+B;CAChD,OAAO,iBAAiB,QAAQ,CAAC,OAAO,MAAM,MAAM,QAAQ,CAAC;AACjE;AAEA,SAAS,UAAU,MAAkB;CACjC,OAAO,IAAI,KAAK,KAAK,QAAQ,CAAC;AAClC;AAEA,SAAS,gBACL,WACA,OACqB;CACrB,IAAI,CAAC,YAAY,KAAK,GAClB,MAAM,IAAIA,sCAAAA,4BACN,GAAG,UAAU,+BACjB;AAER"}

package/dist/temporal-use-case.cjs

@@ -0,0 +1,139 @@
+const require_not_found_error = require("./not-found-error.cjs");
+const require_unexpected_error = require("./unexpected-error.cjs");
+const require_immutable = require("./immutable.cjs");
+const require_use_case = require("./use-case.cjs");
+const require_temporal_guards = require("./temporal-guards.cjs");
+//#region src/core/application/commands/command.ts
+/**
+* Base for use cases that **mutate state** (writes), following CQS.
+*
+* - `Input extends CommandInput` ensures every mutation records who triggered it.
+* - `Output extends Result<unknown, unknown>` ensures business errors are
+*   explicit values, never thrown exceptions.
+*
+* The Command/Query distinction is semantic: the type declares the intent
+* before any implementation exists, guiding code review and API contracts.
+*/
+let Command = class Command extends require_use_case.UseCase {};
+Command = require_immutable.__decorate([require_immutable.version("1.0")], Command);
+//#endregion
+//#region src/core/application/policy-error-mapper.ts
+function mapPolicyEvaluationError(err) {
+	switch (err.kind) {
+		case "INVALID_CONTEXT": return new require_not_found_error.BusinessRuleViolationError(`policy.${err.stage.toLowerCase()}`, err.message, {
+			policyKey: err.policyKey,
+			stage: err.stage
+		}, { cause: err.cause });
+		case "INVALID_POLICY_KEY": return new require_not_found_error.BusinessRuleViolationError("policy.invalid_key", err.message, { rawPolicyKey: err.rawPolicyKey }, { cause: err.cause });
+		case "POLICY_NOT_FOUND": return new require_not_found_error.NotFoundError("Policy", { policyKey: err.policyKey }, { cause: err.cause });
+		case "POLICY_DEFINITION_NOT_FOUND": return new require_not_found_error.NotFoundError("PolicyDefinition", {
+			policyKey: err.policyKey,
+			contextVersion: err.contextVersion,
+			asOf: err.asOf.toISOString()
+		}, { cause: err.cause });
+		case "POLICY_VARIANT_NOT_FOUND": return new require_not_found_error.NotFoundError("PolicyVariant", {
+			policyKey: err.policyKey,
+			policyKind: err.policyKind,
+			payloadSchemaVersion: err.payloadSchemaVersion
+		}, { cause: err.cause });
+		case "ENGINE_FAILURE": return new require_unexpected_error.UnexpectedError(err.message, err.cause, { metadata: {
+			policyKey: err.policyKey,
+			engine: err.engine,
+			engineVersion: err.engineVersion
+		} });
+	}
+}
+//#endregion
+//#region src/core/application/queries/query.ts
+/**
+* Base for use cases that **only read state**, with no side effects, following CQS.
+*
+* - `Data extends QueryOutput` prevents a query from declaring a `void` or
+*   `undefined` success payload, while still allowing primitive projections
+*   and `null` when that makes sense for the read. Failures stay explicit in
+*   `Result<T, E>`.
+* - Override `cacheStrategy()` to declare how infrastructure should cache the
+*   result. By default, no cache is applied.
+*
+* A Query must never mutate persisted data — its execution must be idempotent
+* and safe to call multiple times with the same input.
+*/
+let Query = class Query extends require_use_case.UseCase {
+	cacheStrategy() {
+		return { kind: "NO_CACHE" };
+	}
+};
+Query = require_immutable.__decorate([require_immutable.version("1.0")], Query);
+//#endregion
+//#region src/core/application/temporal/temporal-context.ts
+function assertTemporalContext(temporalContext, fieldName = "temporalContext") {
+	require_temporal_guards.assertValidDate(`${fieldName}.asOf`, temporalContext.asOf);
+	require_temporal_guards.assertValidDate(`${fieldName}.requestedAt`, temporalContext.requestedAt);
+}
+function createTemporalContext(input = {}) {
+	const requestedAt = input.requestedAt ?? /* @__PURE__ */ new Date();
+	const asOf = input.asOf ?? requestedAt;
+	assertTemporalContext({
+		asOf,
+		requestedAt
+	});
+	return require_immutable.makeImmutable({
+		asOf,
+		requestedAt
+	});
+}
+//#endregion
+//#region src/core/application/temporal/temporal-use-case.ts
+var TemporalUseCase = class extends require_use_case.UseCase {
+	resolveTemporalContext(input) {
+		return createTemporalContext(input.temporalContext);
+	}
+	buildPolicySeed(seed, temporalContext) {
+		return Object.freeze({
+			...seed,
+			fields: {
+				...seed.fields,
+				now: new Date(temporalContext.requestedAt.getTime())
+			}
+		});
+	}
+};
+//#endregion
+Object.defineProperty(exports, "Command", {
+	enumerable: true,
+	get: function() {
+		return Command;
+	}
+});
+Object.defineProperty(exports, "Query", {
+	enumerable: true,
+	get: function() {
+		return Query;
+	}
+});
+Object.defineProperty(exports, "TemporalUseCase", {
+	enumerable: true,
+	get: function() {
+		return TemporalUseCase;
+	}
+});
+Object.defineProperty(exports, "assertTemporalContext", {
+	enumerable: true,
+	get: function() {
+		return assertTemporalContext;
+	}
+});
+Object.defineProperty(exports, "createTemporalContext", {
+	enumerable: true,
+	get: function() {
+		return createTemporalContext;
+	}
+});
+Object.defineProperty(exports, "mapPolicyEvaluationError", {
+	enumerable: true,
+	get: function() {
+		return mapPolicyEvaluationError;
+	}
+});
+
+//# sourceMappingURL=temporal-use-case.cjs.map

package/dist/temporal-use-case.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"temporal-use-case.cjs","names":["UseCase","version","BusinessRuleViolationError","NotFoundError","UnexpectedError","UseCase","version","makeImmutable","UseCase"],"sources":["../src/core/application/commands/command.ts","../src/core/application/policy-error-mapper.ts","../src/core/application/queries/query.ts","../src/core/application/temporal/temporal-context.ts","../src/core/application/temporal/temporal-use-case.ts"],"sourcesContent":["import { UseCase } from \"../use-case.js\";\nimport { version } from \"../../versioning/version.js\";\nimport type { Result } from \"../../result/result.js\";\n\nimport { RequestedBy } from \"./requested-by.js\";\n\ninterface CommandInput {\n    readonly requestedBy: RequestedBy;\n}\n\n/**\n * Base for use cases that **mutate state** (writes), following CQS.\n *\n * - `Input extends CommandInput` ensures every mutation records who triggered it.\n * - `Output extends Result<unknown, unknown>` ensures business errors are\n *   explicit values, never thrown exceptions.\n *\n * The Command/Query distinction is semantic: the type declares the intent\n * before any implementation exists, guiding code review and API contracts.\n */\n@version(\"1.0\")\nabstract class Command<\n    Input extends CommandInput,\n    Output extends Result<unknown, unknown> = Result<void, never>,\n> extends UseCase<Input, Output> {}\n\nexport type { CommandInput };\nexport { Command };\n","import {\n    type AppError,\n    BusinessRuleViolationError,\n    NotFoundError,\n    UnexpectedError,\n} from \"../errors/index.js\";\nimport type { PolicyEvaluationError } from \"../policies/index.js\";\n\nexport function mapPolicyEvaluationError(err: PolicyEvaluationError): AppError {\n    switch (err.kind) {\n        case \"INVALID_CONTEXT\":\n            return new BusinessRuleViolationError(\n                `policy.${err.stage.toLowerCase()}`,\n                err.message,\n                { policyKey: err.policyKey, stage: err.stage },\n                { cause: err.cause },\n            );\n        case \"INVALID_POLICY_KEY\":\n            return new BusinessRuleViolationError(\n                \"policy.invalid_key\",\n                err.message,\n                { rawPolicyKey: err.rawPolicyKey },\n                { cause: err.cause },\n            );\n        case \"POLICY_NOT_FOUND\":\n            return new NotFoundError(\n                \"Policy\",\n                { policyKey: err.policyKey },\n                { cause: err.cause },\n            );\n        case \"POLICY_DEFINITION_NOT_FOUND\":\n            return new NotFoundError(\n                \"PolicyDefinition\",\n                {\n                    policyKey: err.policyKey,\n                    contextVersion: err.contextVersion,\n                    asOf: err.asOf.toISOString(),\n                },\n                { cause: err.cause },\n            );\n        case \"POLICY_VARIANT_NOT_FOUND\":\n            return new NotFoundError(\n                \"PolicyVariant\",\n                {\n                    policyKey: err.policyKey,\n                    policyKind: err.policyKind,\n                    payloadSchemaVersion: err.payloadSchemaVersion,\n                },\n                { cause: err.cause },\n            );\n        case \"ENGINE_FAILURE\":\n            return new UnexpectedError(err.message, err.cause, {\n                metadata: {\n                    policyKey: err.policyKey,\n                    engine: err.engine,\n                    engineVersion: err.engineVersion,\n                },\n            });\n    }\n}\n","import { UseCase } from \"../use-case.js\";\nimport { version } from \"../../versioning/version.js\";\nimport type { AppError } from \"../../errors/index.js\";\nimport type { Result } from \"../../result/result.js\";\n\n/**\n * Paginated result of a list query.\n * Use as `Output` when the query returns a collection with pagination metadata.\n */\ninterface Page<T> {\n    readonly items: readonly T[];\n    readonly total: number;\n    readonly page: number;\n    readonly pageSize: number;\n}\n\n/**\n * Cache strategy declared by the query type.\n * Infrastructure reads this value to decide whether and how to cache the result.\n */\ntype CacheStrategy =\n    | { readonly kind: \"NO_CACHE\" }\n    | { readonly kind: \"TIME_TO_LIVE\"; readonly ttlMs: number }\n    | { readonly kind: \"STALE_WHILE_REVALIDATE\"; readonly ttlMs: number };\n\ntype QueryOutput = object | string | number | boolean | bigint | symbol | null;\n\n/**\n * Base for use cases that **only read state**, with no side effects, following CQS.\n *\n * - `Data extends QueryOutput` prevents a query from declaring a `void` or\n *   `undefined` success payload, while still allowing primitive projections\n *   and `null` when that makes sense for the read. Failures stay explicit in\n *   `Result<T, E>`.\n * - Override `cacheStrategy()` to declare how infrastructure should cache the\n *   result. By default, no cache is applied.\n *\n * A Query must never mutate persisted data — its execution must be idempotent\n * and safe to call multiple times with the same input.\n */\n@version(\"1.0\")\nabstract class Query<\n    Input = void,\n    Data extends QueryOutput = never,\n    Failure = AppError,\n> extends UseCase<Input, Result<Data, Failure>> {\n    protected cacheStrategy(): CacheStrategy {\n        return { kind: \"NO_CACHE\" };\n    }\n}\n\nexport type { CacheStrategy, Page, QueryOutput };\nexport { Query };\n","import { makeImmutable } from \"../../shared/immutable.js\";\nimport { assertValidDate } from \"../../shared/temporal-guards.js\";\n\ninterface TemporalContext {\n    readonly asOf: Date;\n    readonly requestedAt: Date;\n}\n\ninterface CreateTemporalContextInput {\n    readonly asOf?: Date;\n    readonly requestedAt?: Date;\n}\n\nfunction assertTemporalContext(\n    temporalContext: TemporalContext,\n    fieldName: string = \"temporalContext\",\n): void {\n    assertValidDate(`${fieldName}.asOf`, temporalContext.asOf);\n    assertValidDate(`${fieldName}.requestedAt`, temporalContext.requestedAt);\n}\n\nfunction createTemporalContext(\n    input: CreateTemporalContextInput = {},\n): TemporalContext {\n    const requestedAt = input.requestedAt ?? new Date();\n    const asOf = input.asOf ?? requestedAt;\n\n    assertTemporalContext({ asOf, requestedAt });\n\n    return makeImmutable({\n        asOf,\n        requestedAt,\n    });\n}\n\nexport {\n    assertTemporalContext,\n    createTemporalContext,\n    type CreateTemporalContextInput,\n    type TemporalContext,\n};\n","import { UseCase } from \"../use-case.js\";\nimport type { ContextSeed } from \"../../policies/index.js\";\nimport type { Result } from \"../../result/result.js\";\n\nimport {\n    createTemporalContext,\n    type TemporalContext,\n} from \"./temporal-context.js\";\n\ninterface TemporalUseCaseInput {\n    readonly temporalContext?: TemporalContext;\n}\n\n/**\n * A {@link ContextSeed} after temporal enrichment by\n * {@link TemporalUseCase.buildPolicySeed}: structurally identical to `TSeed`,\n * except `fields.now` is now guaranteed present as a `Date` (injected from the\n * resolved {@link TemporalContext}). Downstream policies can therefore read\n * `seed.fields.now` without a presence/type guard.\n */\ntype TemporalizedContextSeed<TSeed extends ContextSeed> = Omit<\n    TSeed,\n    \"fields\"\n> & {\n    readonly fields: TSeed[\"fields\"] & { readonly now: Date };\n};\n\nabstract class TemporalUseCase<\n    Input extends object,\n    Output extends Result<unknown, unknown>,\n> extends UseCase<Input & TemporalUseCaseInput, Output> {\n    protected resolveTemporalContext(\n        input: Input & TemporalUseCaseInput,\n    ): TemporalContext {\n        return createTemporalContext(input.temporalContext);\n    }\n\n    protected buildPolicySeed<TSeed extends ContextSeed>(\n        seed: TSeed,\n        temporalContext: TemporalContext,\n    ): TemporalizedContextSeed<TSeed> {\n        return Object.freeze({\n            ...seed,\n            fields: {\n                ...seed.fields,\n                now: new Date(temporalContext.requestedAt.getTime()),\n            },\n        }) as TemporalizedContextSeed<TSeed>;\n    }\n}\n\nexport type { TemporalizedContextSeed, TemporalUseCaseInput };\nexport { TemporalUseCase };\n"],"mappings":";;;;;;;;;;;;;;;;AAoBA,IAAA,UAAA,MACe,gBAGLA,iBAAAA,QAAuB,CAAC;wCAJjCC,kBAAAA,QAAQ,KAAK,CAAA,GAAA,OAAA;;;ACZd,SAAgB,yBAAyB,KAAsC;CAC3E,QAAQ,IAAI,MAAZ;EACI,KAAK,mBACD,OAAO,IAAIC,wBAAAA,2BACP,UAAU,IAAI,MAAM,YAAY,KAChC,IAAI,SACJ;GAAE,WAAW,IAAI;GAAW,OAAO,IAAI;EAAM,GAC7C,EAAE,OAAO,IAAI,MAAM,CACvB;EACJ,KAAK,sBACD,OAAO,IAAIA,wBAAAA,2BACP,sBACA,IAAI,SACJ,EAAE,cAAc,IAAI,aAAa,GACjC,EAAE,OAAO,IAAI,MAAM,CACvB;EACJ,KAAK,oBACD,OAAO,IAAIC,wBAAAA,cACP,UACA,EAAE,WAAW,IAAI,UAAU,GAC3B,EAAE,OAAO,IAAI,MAAM,CACvB;EACJ,KAAK,+BACD,OAAO,IAAIA,wBAAAA,cACP,oBACA;GACI,WAAW,IAAI;GACf,gBAAgB,IAAI;GACpB,MAAM,IAAI,KAAK,YAAY;EAC/B,GACA,EAAE,OAAO,IAAI,MAAM,CACvB;EACJ,KAAK,4BACD,OAAO,IAAIA,wBAAAA,cACP,iBACA;GACI,WAAW,IAAI;GACf,YAAY,IAAI;GAChB,sBAAsB,IAAI;EAC9B,GACA,EAAE,OAAO,IAAI,MAAM,CACvB;EACJ,KAAK,kBACD,OAAO,IAAIC,yBAAAA,gBAAgB,IAAI,SAAS,IAAI,OAAO,EAC/C,UAAU;GACN,WAAW,IAAI;GACf,QAAQ,IAAI;GACZ,eAAe,IAAI;EACvB,EACJ,CAAC;CACT;AACJ;;;;;;;;;;;;;;;;ACnBA,IAAA,QAAA,MACe,cAILC,iBAAAA,QAAsC;CAC5C,gBAAyC;EACrC,OAAO,EAAE,MAAM,WAAW;CAC9B;AACJ;sCATCC,kBAAAA,QAAQ,KAAK,CAAA,GAAA,KAAA;;;AC3Bd,SAAS,sBACL,iBACA,YAAoB,mBAChB;CACJ,wBAAA,gBAAgB,GAAG,UAAU,QAAQ,gBAAgB,IAAI;CACzD,wBAAA,gBAAgB,GAAG,UAAU,eAAe,gBAAgB,WAAW;AAC3E;AAEA,SAAS,sBACL,QAAoC,CAAC,GACtB;CACf,MAAM,cAAc,MAAM,+BAAe,IAAI,KAAK;CAClD,MAAM,OAAO,MAAM,QAAQ;CAE3B,sBAAsB;EAAE;EAAM;CAAY,CAAC;CAE3C,OAAOC,kBAAAA,cAAc;EACjB;EACA;CACJ,CAAC;AACL;;;ACNA,IAAe,kBAAf,cAGUC,iBAAAA,QAA8C;CACpD,uBACI,OACe;EACf,OAAO,sBAAsB,MAAM,eAAe;CACtD;CAEA,gBACI,MACA,iBAC8B;EAC9B,OAAO,OAAO,OAAO;GACjB,GAAG;GACH,QAAQ;IACJ,GAAG,KAAK;IACR,KAAK,IAAI,KAAK,gBAAgB,YAAY,QAAQ,CAAC;GACvD;EACJ,CAAC;CACL;AACJ"}

package/dist/temporal-use-case.d.cts

@@ -0,0 +1,282 @@
+import { t as RequestedBy } from "./requested-by.cjs";
+import { t as AppError } from "./app-error.cjs";
+import { r as Result } from "./result.cjs";
+import { t as DeepReadonly } from "./immutable.cjs";
+import { n as ContractVersion } from "./version.cjs";
+import { b as ContextSeed, r as PolicyEvaluationResult, s as PolicyEvaluationError, t as EvaluateInput } from "./policy-service.cjs";
+
+//#region src/core/application/ports/logger.port.d.ts
+type LogPayload = Record<string, unknown>;
+interface LoggerPort {
+  debug(message: string, payload?: LogPayload): void;
+  info(message: string, payload?: LogPayload): void;
+  warn(message: string, payload?: LogPayload): void;
+  error(message: string, payload?: LogPayload): void;
+}
+//#endregion
+//#region src/core/application/ports/metrics.port.d.ts
+type MetricLabels = Readonly<Record<string, string | number | boolean>>;
+interface MetricsPort {
+  counter(name: string, value: number, labels?: MetricLabels): void;
+  gauge(name: string, value: number, labels?: MetricLabels): void;
+  histogram(name: string, value: number, labels?: MetricLabels): void;
+}
+//#endregion
+//#region src/core/application/ports/tracer.port.d.ts
+type TraceAttributeValue = string | number | boolean;
+interface TraceSpan {
+  setAttribute(key: string, value: TraceAttributeValue): void;
+  recordException(error: unknown): void;
+  end(): void;
+}
+interface TracerPort {
+  startSpan(name: string, attributes?: Record<string, TraceAttributeValue>): TraceSpan;
+}
+//#endregion
+//#region src/core/application/use-case.d.ts
+type MaybePromise<T> = T | Promise<T>;
+/**
+ * Observability adapters a use case may opt into.
+ *
+ * All fields are optional: a use case that provides none keeps the plain
+ * `input → Result` behavior with zero overhead. When provided, {@link UseCase.run}
+ * instruments every execution around `execute()` — opening a span, recording
+ * duration, counting outcomes, and logging business/unexpected failures.
+ */
+interface UseCaseObservability {
+  readonly logger?: LoggerPort;
+  readonly metrics?: MetricsPort;
+  readonly tracer?: TracerPort;
+}
+declare abstract class UseCase<Input = void, Output extends Result<unknown, unknown> = Result<void, never>> {
+  static readonly CONTRACT_VERSION: ContractVersion;
+  get contractVersion(): ContractVersion;
+  /**
+   * Runs the use case.
+   *
+   * `run()` is the single seam every use case crosses, so it is where
+   * cross-cutting instrumentation lives. When {@link observability} exposes
+   * any adapter, the call to `execute()` is wrapped with tracing, metrics and
+   * failure logging; otherwise it delegates directly with no overhead.
+   *
+   * Observability is strictly side-effecting: a misbehaving adapter never
+   * changes the business result nor masks a thrown error — its own failures
+   * are swallowed.
+   */
+  run(input: Input): Promise<Output>;
+  /**
+   * Adapters used to instrument {@link run}. Override to opt a use case into
+   * tracing/metrics/logging. Returns an empty object by default, which keeps
+   * the plain delegating behavior.
+   */
+  protected observability(): UseCaseObservability;
+  /**
+   * Stable identity used for span names and metric labels. Defaults to the
+   * runtime class name; override when bundling/minification would otherwise
+   * erase a meaningful name.
+   */
+  protected get useCaseName(): string;
+  protected abstract execute(input: Input): MaybePromise<Output>;
+  private runInstrumented;
+}
+//#endregion
+//#region src/core/application/commands/command.d.ts
+interface CommandInput {
+  readonly requestedBy: RequestedBy;
+}
+/**
+ * Base for use cases that **mutate state** (writes), following CQS.
+ *
+ * - `Input extends CommandInput` ensures every mutation records who triggered it.
+ * - `Output extends Result<unknown, unknown>` ensures business errors are
+ *   explicit values, never thrown exceptions.
+ *
+ * The Command/Query distinction is semantic: the type declares the intent
+ * before any implementation exists, guiding code review and API contracts.
+ */
+declare abstract class Command<Input extends CommandInput, Output extends Result<unknown, unknown> = Result<void, never>> extends UseCase<Input, Output> {}
+//#endregion
+//#region src/core/application/ports/policy-port.d.ts
+type PolicyEvaluationInput = EvaluateInput;
+type PolicyEvaluationOutput = PolicyEvaluationResult;
+/**
+ * Failure surfaced by {@link PolicyPort.evaluate}.
+ *
+ * This is the *post-mapping* boundary: the structured `PolicyEvaluationError`
+ * union produced inside the policies module is expected to have already been
+ * translated into an {@link AppError} (e.g. via `mapPolicyEvaluationError`)
+ * before it reaches a use case. Named distinctly from the policies-layer
+ * `PolicyEvaluationError` to avoid a collision on the public surface.
+ */
+type PolicyPortError = AppError;
+interface PolicyPort {
+  evaluate(input: PolicyEvaluationInput): Promise<Result<PolicyEvaluationOutput, PolicyPortError>>;
+}
+//#endregion
+//#region src/core/application/ports/repository.port.d.ts
+/**
+ * Persistence port for an aggregate in the imperative style: absence is
+ * modelled as `null`, and failures (missing row on delete, optimistic
+ * concurrency conflicts, infrastructure errors) surface as thrown exceptions.
+ *
+ * Prefer {@link ResultRepository} when you want those persistence outcomes to
+ * be explicit, recoverable values rather than exceptions.
+ */
+interface Repository<TEntity, TId> {
+  findById(id: TId): Promise<TEntity | null>;
+  save(entity: TEntity): Promise<void>;
+  delete(id: TId): Promise<void>;
+}
+/**
+ * `Result`-returning counterpart of {@link Repository}, aligned with the
+ * "errors as values" philosophy used by `Command` / `UseCase`.
+ *
+ * Where {@link Repository} returns `Promise<void>` from `save`/`delete` and
+ * relies on thrown exceptions, this variant lets a repository *signal*
+ * recoverable persistence outcomes without breaking control flow — for
+ * example a `NotFoundError` when updating/deleting a missing aggregate, or a
+ * `ConflictError` on an optimistic-concurrency version mismatch. A successful
+ * write resolves to `Result.ok(undefined)`.
+ *
+ * `findById` keeps `null` as the "not present" answer to a lookup (not an
+ * error) while still wrapping the call in a `Result` so genuine failures
+ * (e.g. a connectivity error) stay in band.
+ *
+ * `TError` defaults to {@link AppError} to match the rest of the application
+ * boundary (see `PolicyPortError`); narrow it per repository when the failure
+ * set is known, e.g. `ResultRepository<Order, OrderId, NotFoundError | ConflictError>`.
+ */
+interface ResultRepository<TEntity, TId, TError = AppError> {
+  findById(id: TId): Promise<Result<TEntity | null, TError>>;
+  save(entity: TEntity): Promise<Result<void, TError>>;
+  delete(id: TId): Promise<Result<void, TError>>;
+}
+//#endregion
+//#region src/core/domain/temporal/transaction-time.d.ts
+/**
+ * Represents transaction time (Transaction Time).
+ * Defines when the system learned about or recorded a piece of information.
+ * Useful for auditing and reconstructing system state at a specific past moment.
+ */
+interface TransactionTime {
+  /** When the information was first recorded in the system. */
+  readonly recordedAt: Date;
+  /** When this information was superseded or invalidated by a newer version. */
+  readonly supersededAt?: Date;
+}
+//#endregion
+//#region src/core/domain/temporal/valid-time.d.ts
+/**
+ * Represents business time (Valid Time).
+ * Defines when a piece of information is considered true or in effect in the real world.
+ */
+interface ValidTime {
+  /** Start of the validity window (inclusive). */
+  readonly from: Date;
+  /** End of the validity window (exclusive). When absent, the information is still in effect. */
+  readonly to?: Date;
+}
+//#endregion
+//#region src/core/domain/temporal/temporal-snapshot.d.ts
+/**
+ * Pairs a domain datum with its time dimensions (Business and Transaction).
+ * It is the representation of an entry in the append-only (historical) table.
+ */
+interface TemporalSnapshot<T> {
+  /** The data or state captured by the snapshot. */
+  readonly data: DeepReadonly<T>;
+  /** Period during which this datum was valid in the real world. */
+  readonly validTime: ValidTime;
+  /** Period during which this record was the state known to the system. */
+  readonly txTime: TransactionTime;
+}
+//#endregion
+//#region src/core/application/ports/temporal-repository.port.d.ts
+type TemporalHistory<TEntity> = readonly TemporalSnapshot<TEntity>[];
+interface TemporalRepository<TEntity, TId> extends Repository<TEntity, TId> {
+  findAsOf(id: TId, asOf: Date): Promise<TEntity | null>;
+  findAtTransaction(id: TId, txTime: Date): Promise<TEntity | null>;
+  findHistory(id: TId): Promise<TemporalHistory<TEntity>>;
+  save(entity: TEntity, validFrom?: Date): Promise<void>;
+}
+//#endregion
+//#region src/core/application/policy-error-mapper.d.ts
+declare function mapPolicyEvaluationError(err: PolicyEvaluationError): AppError;
+//#endregion
+//#region src/core/application/queries/query.d.ts
+/**
+ * Paginated result of a list query.
+ * Use as `Output` when the query returns a collection with pagination metadata.
+ */
+interface Page<T> {
+  readonly items: readonly T[];
+  readonly total: number;
+  readonly page: number;
+  readonly pageSize: number;
+}
+/**
+ * Cache strategy declared by the query type.
+ * Infrastructure reads this value to decide whether and how to cache the result.
+ */
+type CacheStrategy = {
+  readonly kind: "NO_CACHE";
+} | {
+  readonly kind: "TIME_TO_LIVE";
+  readonly ttlMs: number;
+} | {
+  readonly kind: "STALE_WHILE_REVALIDATE";
+  readonly ttlMs: number;
+};
+type QueryOutput = object | string | number | boolean | bigint | symbol | null;
+/**
+ * Base for use cases that **only read state**, with no side effects, following CQS.
+ *
+ * - `Data extends QueryOutput` prevents a query from declaring a `void` or
+ *   `undefined` success payload, while still allowing primitive projections
+ *   and `null` when that makes sense for the read. Failures stay explicit in
+ *   `Result<T, E>`.
+ * - Override `cacheStrategy()` to declare how infrastructure should cache the
+ *   result. By default, no cache is applied.
+ *
+ * A Query must never mutate persisted data — its execution must be idempotent
+ * and safe to call multiple times with the same input.
+ */
+declare abstract class Query<Input = void, Data extends QueryOutput = never, Failure = AppError> extends UseCase<Input, Result<Data, Failure>> {
+  protected cacheStrategy(): CacheStrategy;
+}
+//#endregion
+//#region src/core/application/temporal/temporal-context.d.ts
+interface TemporalContext {
+  readonly asOf: Date;
+  readonly requestedAt: Date;
+}
+interface CreateTemporalContextInput {
+  readonly asOf?: Date;
+  readonly requestedAt?: Date;
+}
+declare function assertTemporalContext(temporalContext: TemporalContext, fieldName?: string): void;
+declare function createTemporalContext(input?: CreateTemporalContextInput): TemporalContext;
+//#endregion
+//#region src/core/application/temporal/temporal-use-case.d.ts
+interface TemporalUseCaseInput {
+  readonly temporalContext?: TemporalContext;
+}
+/**
+ * A {@link ContextSeed} after temporal enrichment by
+ * {@link TemporalUseCase.buildPolicySeed}: structurally identical to `TSeed`,
+ * except `fields.now` is now guaranteed present as a `Date` (injected from the
+ * resolved {@link TemporalContext}). Downstream policies can therefore read
+ * `seed.fields.now` without a presence/type guard.
+ */
+type TemporalizedContextSeed<TSeed extends ContextSeed> = Omit<TSeed, "fields"> & {
+  readonly fields: TSeed["fields"] & {
+    readonly now: Date;
+  };
+};
+declare abstract class TemporalUseCase<Input extends object, Output extends Result<unknown, unknown>> extends UseCase<Input & TemporalUseCaseInput, Output> {
+  protected resolveTemporalContext(input: Input & TemporalUseCaseInput): TemporalContext;
+  protected buildPolicySeed<TSeed extends ContextSeed>(seed: TSeed, temporalContext: TemporalContext): TemporalizedContextSeed<TSeed>;
+}
+//#endregion
+export { LogPayload as A, UseCase as C, TracerPort as D, TraceSpan as E, MetricLabels as O, MaybePromise as S, TraceAttributeValue as T, PolicyEvaluationOutput as _, TemporalContext as a, Command as b, CacheStrategy as c, mapPolicyEvaluationError as d, TemporalHistory as f, PolicyEvaluationInput as g, ResultRepository as h, CreateTemporalContextInput as i, LoggerPort as j, MetricsPort as k, Page as l, Repository as m, TemporalUseCaseInput as n, assertTemporalContext as o, TemporalRepository as p, TemporalizedContextSeed as r, createTemporalContext as s, TemporalUseCase as t, Query as u, PolicyPort as v, UseCaseObservability as w, CommandInput as x, PolicyPortError as y };
+//# sourceMappingURL=temporal-use-case.d.cts.map