@cullet/erp-core 1.2.0 → 1.3.0

package/dist/result.cjs

@@ -0,0 +1,135 @@
+//#region src/core/result/result.ts
+/**
+* Represents the outcome of an operation that may succeed or fail.
+* Useful for avoiding excessive exceptions and making error flows explicit.
+*/
+var Result = class Result {
+	constructor() {}
+	/**
+	* Creates a success result containing a value.
+	*/
+	static ok(value) {
+		return new Ok(value);
+	}
+	/**
+	* Creates an error result containing an error object.
+	*/
+	static err(error) {
+		return new Err(error);
+	}
+	/**
+	* Returns the value when this is success, or null when this is an error.
+	*/
+	getOrNull() {
+		return this.match({
+			ok: (value) => value,
+			err: () => null
+		});
+	}
+	/**
+	* Returns the error when this is a failure, or null when this is a success.
+	*/
+	errorOrNull() {
+		return this.match({
+			ok: () => null,
+			err: (error) => error
+		});
+	}
+	/**
+	* Returns the value when this is a success, or throws the error when this is a failure.
+	*/
+	getOrThrow() {
+		return this.match({
+			ok: (value) => value,
+			err: (error) => {
+				throw error instanceof Error ? error : new Error(String(error));
+			}
+		});
+	}
+	/**
+	* Transforms the success value using the provided function. Keeps the error when this is a failure.
+	*/
+	map(transform) {
+		return this.match({
+			ok: (value) => Result.ok(transform(value)),
+			err: (error) => Result.err(error)
+		});
+	}
+	/**
+	* Transforms the error using the provided function. Keeps the value when this is a success.
+	*/
+	mapError(transform) {
+		return this.match({
+			ok: (value) => Result.ok(value),
+			err: (error) => Result.err(transform(error))
+		});
+	}
+	/**
+	* Chains another operation that returns a Result when this result is a success.
+	*/
+	flatMap(transform) {
+		return this.match({
+			ok: (value) => transform(value),
+			err: (error) => Result.err(error)
+		});
+	}
+};
+/**
+* Success variant of Result.
+*/
+var Ok = class extends Result {
+	constructor(value) {
+		super();
+		this.value = value;
+		Object.freeze(this);
+	}
+	isOk() {
+		return true;
+	}
+	isErr() {
+		return false;
+	}
+	match(handlers) {
+		return handlers.ok(this.value);
+	}
+};
+/**
+* Error variant of Result.
+*/
+var Err = class extends Result {
+	constructor(error) {
+		super();
+		this.error = error;
+		Object.freeze(this);
+	}
+	isOk() {
+		return false;
+	}
+	isErr() {
+		return true;
+	}
+	match(handlers) {
+		return handlers.err(this.error);
+	}
+};
+//#endregion
+Object.defineProperty(exports, "Err", {
+	enumerable: true,
+	get: function() {
+		return Err;
+	}
+});
+Object.defineProperty(exports, "Ok", {
+	enumerable: true,
+	get: function() {
+		return Ok;
+	}
+});
+Object.defineProperty(exports, "Result", {
+	enumerable: true,
+	get: function() {
+		return Result;
+	}
+});
+
+//# sourceMappingURL=result.cjs.map

package/dist/result.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.cjs","names":[],"sources":["../src/core/result/result.ts"],"sourcesContent":["/**\n * Represents the outcome of an operation that may succeed or fail.\n * Useful for avoiding excessive exceptions and making error flows explicit.\n */\nexport abstract class Result<T, E> {\n    protected constructor() {\n        // prevent direct instantiation\n    }\n\n    /**\n     * Creates a success result containing a value.\n     */\n    static ok<T>(value: T): Result<T, never> {\n        return new Ok(value);\n    }\n\n    /**\n     * Creates an error result containing an error object.\n     */\n    static err<E>(error: E): Result<never, E> {\n        return new Err(error);\n    }\n\n    /**\n     * Returns true when this is a success result.\n     */\n    abstract isOk(): this is Ok<T>;\n\n    /**\n     * Returns true when this is an error result.\n     */\n    abstract isErr(): this is Err<E>;\n\n    /**\n     * Runs a handler based on the result state (similar to pattern matching).\n     */\n    abstract match<R>(handlers: {\n        ok: (value: T) => R;\n        err: (error: E) => R;\n    }): R;\n\n    /**\n     * Returns the value when this is success, or null when this is an error.\n     */\n    getOrNull(): T | null {\n        return this.match({\n            ok: (value) => value,\n            err: () => null,\n        });\n    }\n\n    /**\n     * Returns the error when this is a failure, or null when this is a success.\n     */\n    errorOrNull(): E | null {\n        return this.match({\n            ok: () => null,\n            err: (error) => error,\n        });\n    }\n\n    /**\n     * Returns the value when this is a success, or throws the error when this is a failure.\n     */\n    getOrThrow(): T {\n        return this.match({\n            ok: (value) => value,\n            err: (error) => {\n                throw error instanceof Error ? error : new Error(String(error));\n            },\n        });\n    }\n\n    /**\n     * Transforms the success value using the provided function. Keeps the error when this is a failure.\n     */\n    map<R>(transform: (value: T) => R): Result<R, E> {\n        return this.match<Result<R, E>>({\n            ok: (value) => Result.ok(transform(value)),\n            // TS does not \"see\" variance here; the cast is intentional and safe:\n            // Err carries no T, so it can be widened to Result<R, E> safely.\n            err: (error) => Result.err(error) as unknown as Result<R, E>,\n        });\n    }\n\n    /**\n     * Transforms the error using the provided function. Keeps the value when this is a success.\n     */\n    mapError<F>(transform: (error: E) => F): Result<T, F> {\n        return this.match<Result<T, F>>({\n            // Ok carries no E, so it can be widened to Result<T, F>.\n            ok: (value) => Result.ok(value) as unknown as Result<T, F>,\n            err: (error) => Result.err(transform(error)),\n        });\n    }\n\n    /**\n     * Chains another operation that returns a Result when this result is a success.\n     */\n    flatMap<R>(transform: (value: T) => Result<R, E>): Result<R, E> {\n        return this.match<Result<R, E>>({\n            ok: (value) => transform(value),\n            err: (error) => Result.err(error) as unknown as Result<R, E>,\n        });\n    }\n}\n\n/**\n * Success variant of Result.\n */\nexport class Ok<T> extends Result<T, never> {\n    public readonly value: T;\n\n    constructor(value: T) {\n        super();\n        this.value = value;\n        Object.freeze(this);\n    }\n\n    isOk(): this is Ok<T> {\n        return true;\n    }\n\n    isErr(): this is Err<never> {\n        return false;\n    }\n\n    match<R>(handlers: { ok: (value: T) => R; err: (error: never) => R }): R {\n        return handlers.ok(this.value);\n    }\n}\n\n/**\n * Error variant of Result.\n */\nexport class Err<E> extends Result<never, E> {\n    public readonly error: E;\n\n    constructor(error: E) {\n        super();\n        this.error = error;\n        Object.freeze(this);\n    }\n\n    isOk(): this is Ok<never> {\n        return false;\n    }\n\n    isErr(): this is Err<E> {\n        return true;\n    }\n\n    match<R>(handlers: { ok: (value: never) => R; err: (error: E) => R }): R {\n        return handlers.err(this.error);\n    }\n}\n"],"mappings":";;;;;AAIA,IAAsB,SAAtB,MAAsB,OAAa;CAC/B,cAAwB,CAExB;;;;CAKA,OAAO,GAAM,OAA4B;EACrC,OAAO,IAAI,GAAG,KAAK;CACvB;;;;CAKA,OAAO,IAAO,OAA4B;EACtC,OAAO,IAAI,IAAI,KAAK;CACxB;;;;CAuBA,YAAsB;EAClB,OAAO,KAAK,MAAM;GACd,KAAK,UAAU;GACf,WAAW;EACf,CAAC;CACL;;;;CAKA,cAAwB;EACpB,OAAO,KAAK,MAAM;GACd,UAAU;GACV,MAAM,UAAU;EACpB,CAAC;CACL;;;;CAKA,aAAgB;EACZ,OAAO,KAAK,MAAM;GACd,KAAK,UAAU;GACf,MAAM,UAAU;IACZ,MAAM,iBAAiB,QAAQ,QAAQ,IAAI,MAAM,OAAO,KAAK,CAAC;GAClE;EACJ,CAAC;CACL;;;;CAKA,IAAO,WAA0C;EAC7C,OAAO,KAAK,MAAoB;GAC5B,KAAK,UAAU,OAAO,GAAG,UAAU,KAAK,CAAC;GAGzC,MAAM,UAAU,OAAO,IAAI,KAAK;EACpC,CAAC;CACL;;;;CAKA,SAAY,WAA0C;EAClD,OAAO,KAAK,MAAoB;GAE5B,KAAK,UAAU,OAAO,GAAG,KAAK;GAC9B,MAAM,UAAU,OAAO,IAAI,UAAU,KAAK,CAAC;EAC/C,CAAC;CACL;;;;CAKA,QAAW,WAAqD;EAC5D,OAAO,KAAK,MAAoB;GAC5B,KAAK,UAAU,UAAU,KAAK;GAC9B,MAAM,UAAU,OAAO,IAAI,KAAK;EACpC,CAAC;CACL;AACJ;;;;AAKA,IAAa,KAAb,cAA2B,OAAiB;CAGxC,YAAY,OAAU;EAClB,MAAM;EACN,KAAK,QAAQ;EACb,OAAO,OAAO,IAAI;CACtB;CAEA,OAAsB;EAClB,OAAO;CACX;CAEA,QAA4B;EACxB,OAAO;CACX;CAEA,MAAS,UAAgE;EACrE,OAAO,SAAS,GAAG,KAAK,KAAK;CACjC;AACJ;;;;AAKA,IAAa,MAAb,cAA4B,OAAiB;CAGzC,YAAY,OAAU;EAClB,MAAM;EACN,KAAK,QAAQ;EACb,OAAO,OAAO,IAAI;CACtB;CAEA,OAA0B;EACtB,OAAO;CACX;CAEA,QAAwB;EACpB,OAAO;CACX;CAEA,MAAS,UAAgE;EACrE,OAAO,SAAS,IAAI,KAAK,KAAK;CAClC;AACJ"}

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,191 @@
+const require_unexpected_error = require("./unexpected-error.cjs");
+const require_not_found_error = require("./not-found-error.cjs");
+const require_validation_code = require("./validation-code.cjs");
+const require_validation_field = require("./validation-field.cjs");
+const require_validation_exception = require("./validation-exception.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/requested-by.ts
+const REQUESTED_BY_FIELD = require_validation_field.ValidationField.of("requestedBy");
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const SYSTEM_IDENTITY_PATTERN = /^system:[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+var RequestedBy = class RequestedBy {
+	constructor(kind, raw) {
+		this.kind = kind;
+		this.raw = raw;
+		Object.freeze(this);
+	}
+	/** Builds from a human user ID (must be a UUID). */
+	static fromUser(userId) {
+		if (!UUID_PATTERN.test(userId)) throw new require_validation_exception.InvalidValueException(REQUESTED_BY_FIELD, require_validation_code.ValidationCode.INVALID_FORMAT, `requestedBy: user identity must be a UUID, got "${userId}"`);
+		return new RequestedBy("user", userId);
+	}
+	/**
+	* Builds from a system identity.
+	* Only accepts the format "system:<job>", where <job> matches [a-z][a-z0-9]*(-[a-z0-9]+)*.
+	*/
+	static fromSystem(systemIdentity) {
+		if (!SYSTEM_IDENTITY_PATTERN.test(systemIdentity)) throw new require_validation_exception.InvalidValueException(REQUESTED_BY_FIELD, require_validation_code.ValidationCode.INVALID_FORMAT, `requestedBy: system identity must match "system:<job>" (e.g. "system:late-fee-job"), got "${systemIdentity}"`);
+		return new RequestedBy("system", systemIdentity);
+	}
+	/**
+	* Infers the kind from the raw value.
+	* Use when the origin (user vs system) is not known at the call-site.
+	*/
+	static parse(raw) {
+		if (UUID_PATTERN.test(raw)) return new RequestedBy("user", raw);
+		if (SYSTEM_IDENTITY_PATTERN.test(raw)) return new RequestedBy("system", raw);
+		throw new require_validation_exception.InvalidValueException(REQUESTED_BY_FIELD, require_validation_code.ValidationCode.INVALID_FORMAT, `requestedBy must be a UUID (user) or "system:<job>" (system), got "${raw}"`);
+	}
+	get isUser() {
+		return this.kind === "user";
+	}
+	get isSystem() {
+		return this.kind === "system";
+	}
+	toString() {
+		return this.raw;
+	}
+};
+//#endregion
+//#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, "RequestedBy", {
+	enumerable: true,
+	get: function() {
+		return RequestedBy;
+	}
+});
+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":["ValidationField","InvalidValueException","ValidationCode","UseCase","version","BusinessRuleViolationError","NotFoundError","UnexpectedError","UseCase","version","makeImmutable","UseCase"],"sources":["../src/core/application/commands/requested-by.ts","../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 { ValidationCode } from \"../../exceptions/validation-code.js\";\nimport { InvalidValueException } from \"../../exceptions/validation-exception.js\";\nimport { ValidationField } from \"../../exceptions/validation-field.js\";\n\n// Identifies who triggered a Command.\n// Two valid formats:\n//   - Human user: UUID v4 (e.g.: \"550e8400-e29b-41d4-a716-446655440000\")\n//   - System identity: \"system:<job>\" where <job> is [a-z][a-z0-9]*(-[a-z0-9]+)*\n//     (e.g.: \"system:late-fee-job\", \"system:email-sender\")\n//\n// The split between `fromUser` / `fromSystem` / `parse` exists to make intent\n// explicit at the call-site: whoever builds the value knows where it came from.\n\ntype RequestedByKind = \"user\" | \"system\";\n\nconst REQUESTED_BY_FIELD = ValidationField.of(\"requestedBy\");\n\nconst UUID_PATTERN =\n    /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;\n\n// system:<job> where <job> starts with a lowercase letter and may have hyphens between segments\nconst SYSTEM_IDENTITY_PATTERN = /^system:[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;\n\nclass RequestedBy {\n    readonly kind: RequestedByKind;\n    readonly raw: string;\n\n    private constructor(kind: RequestedByKind, raw: string) {\n        this.kind = kind;\n        this.raw = raw;\n        Object.freeze(this);\n    }\n\n    /** Builds from a human user ID (must be a UUID). */\n    static fromUser(userId: string): RequestedBy {\n        if (!UUID_PATTERN.test(userId)) {\n            throw new InvalidValueException(\n                REQUESTED_BY_FIELD,\n                ValidationCode.INVALID_FORMAT,\n                `requestedBy: user identity must be a UUID, got \"${userId}\"`,\n            );\n        }\n\n        return new RequestedBy(\"user\", userId);\n    }\n\n    /**\n     * Builds from a system identity.\n     * Only accepts the format \"system:<job>\", where <job> matches [a-z][a-z0-9]*(-[a-z0-9]+)*.\n     */\n    static fromSystem(systemIdentity: string): RequestedBy {\n        if (!SYSTEM_IDENTITY_PATTERN.test(systemIdentity)) {\n            throw new InvalidValueException(\n                REQUESTED_BY_FIELD,\n                ValidationCode.INVALID_FORMAT,\n                `requestedBy: system identity must match \"system:<job>\" (e.g. \"system:late-fee-job\"), got \"${systemIdentity}\"`,\n            );\n        }\n\n        return new RequestedBy(\"system\", systemIdentity);\n    }\n\n    /**\n     * Infers the kind from the raw value.\n     * Use when the origin (user vs system) is not known at the call-site.\n     */\n    static parse(raw: string): RequestedBy {\n        if (UUID_PATTERN.test(raw)) {\n            return new RequestedBy(\"user\", raw);\n        }\n\n        if (SYSTEM_IDENTITY_PATTERN.test(raw)) {\n            return new RequestedBy(\"system\", raw);\n        }\n\n        throw new InvalidValueException(\n            REQUESTED_BY_FIELD,\n            ValidationCode.INVALID_FORMAT,\n            `requestedBy must be a UUID (user) or \"system:<job>\" (system), got \"${raw}\"`,\n        );\n    }\n\n    get isUser(): boolean {\n        return this.kind === \"user\";\n    }\n\n    get isSystem(): boolean {\n        return this.kind === \"system\";\n    }\n\n    toString(): string {\n        return this.raw;\n    }\n}\n\nexport type { RequestedByKind };\nexport { RequestedBy };\n","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":"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"}