@cullet/erp-core 1.0.11 → 1.2.0

package/dist/result.js

@@ -0,0 +1,118 @@
+//#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
+export { Ok as n, Result as r, Err as t };
+
+//# sourceMappingURL=result.js.map

package/dist/result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.js","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.js

@@ -0,0 +1,42 @@
+import { t as DomainException } from "./domain-exception.js";
+//#region src/core/domain/rulesets/ruleset-registry.ts
+var RulesetRegistryError = class extends 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
+export { RulesetRegistry as t };
+
+//# sourceMappingURL=ruleset-registry.js.map

package/dist/ruleset-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ruleset-registry.js","names":[],"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,cAAmC,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.d.ts

@@ -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.js";
+export { CreationRuleset, InvariantRuleset, Ruleset, RulesetId, RulesetRegistry, ValueObjectRuleset };

package/dist/rulesets/index.js

@@ -0,0 +1,2 @@
+import { t as RulesetRegistry } from "../ruleset-registry.js";
+export { RulesetRegistry };

package/dist/temporal-guards.js

@@ -0,0 +1,15 @@
+import { t as InvariantViolationException } from "./invariant-violation-exception.js";
+//#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 InvariantViolationException(`${fieldName} must be a valid Date instance`);
+}
+//#endregion
+export { cloneDate as n, isValidDate as r, assertValidDate as t };
+
+//# sourceMappingURL=temporal-guards.js.map

package/dist/temporal-guards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"temporal-guards.js","names":[],"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,IAAI,4BACN,GAAG,UAAU,+BACjB;AAER"}

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

@@ -0,0 +1,304 @@
+import { n as ContractVersion } from "./version.js";
+import { a as Result } from "./outcome.js";
+import { t as AppError } from "./app-error.js";
+import { b as ContextSeed, r as PolicyEvaluationResult, s as PolicyEvaluationError, t as EvaluateInput } from "./policy-service.js";
+import { t as DeepReadonly } from "./immutable.js";
+
+//#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/requested-by.d.ts
+type RequestedByKind = "user" | "system";
+declare class RequestedBy {
+  readonly kind: RequestedByKind;
+  readonly raw: string;
+  private constructor();
+  /** Builds from a human user ID (must be a UUID). */
+  static fromUser(userId: string): RequestedBy;
+  /**
+   * 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: string): RequestedBy;
+  /**
+   * Infers the kind from the raw value.
+   * Use when the origin (user vs system) is not known at the call-site.
+   */
+  static parse(raw: string): RequestedBy;
+  get isUser(): boolean;
+  get isSystem(): boolean;
+  toString(): string;
+}
+//#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 { MetricLabels as A, RequestedByKind as C, TraceAttributeValue as D, UseCaseObservability as E, LogPayload as M, LoggerPort as N, TraceSpan as O, RequestedBy as S, UseCase 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, MetricsPort as j, TracerPort 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, MaybePromise as w, CommandInput as x, PolicyPortError as y };
+//# sourceMappingURL=temporal-use-case.d.ts.map

package/dist/temporal-use-case.js

@@ -0,0 +1,150 @@
+import { t as UnexpectedError } from "./unexpected-error.js";
+import { n as BusinessRuleViolationError, t as NotFoundError } from "./not-found-error.js";
+import { t as ValidationCode } from "./validation-code.js";
+import { t as ValidationField } from "./validation-field.js";
+import { t as InvalidValueException } from "./validation-exception.js";
+import { i as version, n as __decorate, t as makeImmutable } from "./immutable.js";
+import { t as UseCase } from "./use-case.js";
+import { t as assertValidDate } from "./temporal-guards.js";
+//#region src/core/application/commands/requested-by.ts
+const REQUESTED_BY_FIELD = ValidationField.of("requestedBy");
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+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 InvalidValueException(REQUESTED_BY_FIELD, 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 InvalidValueException(REQUESTED_BY_FIELD, 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 InvalidValueException(REQUESTED_BY_FIELD, 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 UseCase {};
+Command = __decorate([version("1.0")], Command);
+//#endregion
+//#region src/core/application/policy-error-mapper.ts
+function mapPolicyEvaluationError(err) {
+	switch (err.kind) {
+		case "INVALID_CONTEXT": return new BusinessRuleViolationError(`policy.${err.stage.toLowerCase()}`, err.message, {
+			policyKey: err.policyKey,
+			stage: err.stage
+		}, { cause: err.cause });
+		case "INVALID_POLICY_KEY": return new BusinessRuleViolationError("policy.invalid_key", err.message, { rawPolicyKey: err.rawPolicyKey }, { cause: err.cause });
+		case "POLICY_NOT_FOUND": return new NotFoundError("Policy", { policyKey: err.policyKey }, { cause: err.cause });
+		case "POLICY_DEFINITION_NOT_FOUND": return new NotFoundError("PolicyDefinition", {
+			policyKey: err.policyKey,
+			contextVersion: err.contextVersion,
+			asOf: err.asOf.toISOString()
+		}, { cause: err.cause });
+		case "POLICY_VARIANT_NOT_FOUND": return new NotFoundError("PolicyVariant", {
+			policyKey: err.policyKey,
+			policyKind: err.policyKind,
+			payloadSchemaVersion: err.payloadSchemaVersion
+		}, { cause: err.cause });
+		case "ENGINE_FAILURE": return new 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 UseCase {
+	cacheStrategy() {
+		return { kind: "NO_CACHE" };
+	}
+};
+Query = __decorate([version("1.0")], Query);
+//#endregion
+//#region src/core/application/temporal/temporal-context.ts
+function assertTemporalContext(temporalContext, fieldName = "temporalContext") {
+	assertValidDate(`${fieldName}.asOf`, temporalContext.asOf);
+	assertValidDate(`${fieldName}.requestedAt`, temporalContext.requestedAt);
+}
+function createTemporalContext(input = {}) {
+	const requestedAt = input.requestedAt ?? /* @__PURE__ */ new Date();
+	const asOf = input.asOf ?? requestedAt;
+	assertTemporalContext({
+		asOf,
+		requestedAt
+	});
+	return makeImmutable({
+		asOf,
+		requestedAt
+	});
+}
+//#endregion
+//#region src/core/application/temporal/temporal-use-case.ts
+var TemporalUseCase = class extends UseCase {
+	resolveTemporalContext(input) {
+		return createTemporalContext(input.temporalContext);
+	}
+	buildPolicySeed(seed, temporalContext) {
+		return Object.freeze({
+			...seed,
+			fields: {
+				...seed.fields,
+				now: new Date(temporalContext.requestedAt.getTime())
+			}
+		});
+	}
+};
+//#endregion
+export { mapPolicyEvaluationError as a, Query as i, assertTemporalContext as n, Command as o, createTemporalContext as r, RequestedBy as s, TemporalUseCase as t };
+
+//# sourceMappingURL=temporal-use-case.js.map