@cullet/erp-core 1.4.0 → 2.0.0

package/dist/temporal-use-case.js

@@ -1,8 +1,128 @@
+import { t as AppError } from "./app-error.js";
 import { n as BusinessRuleViolationError, t as NotFoundError } from "./not-found-error.js";
-import { t as UnexpectedError } from "./unexpected-error.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";
+import { t as UnexpectedError } from "./unexpected-error.js";
+import { i as version, n as makeImmutable } from "./immutable.js";
+import { t as __decorate } from "./decorate.js";
+//#region src/core/application/use-case.ts
+const EXECUTION_COUNTER = "use_case.executions";
+const DURATION_HISTOGRAM = "use_case.duration_ms";
+let UseCase = class UseCase {
+	get contractVersion() {
+		return this.constructor.CONTRACT_VERSION;
+	}
+	/**
+	* 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.
+	*/
+	async run(input) {
+		const observability = this.observability();
+		if (!observability.logger && !observability.metrics && !observability.tracer) return await this.execute(input);
+		return await this.runInstrumented(input, observability);
+	}
+	/**
+	* 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.
+	*/
+	observability() {
+		return {};
+	}
+	/**
+	* 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.
+	*/
+	get useCaseName() {
+		return this.constructor.name;
+	}
+	/**
+	* Extra attributes stamped onto the span and every metric emitted for this
+	* execution. Override to attach stable, **low-cardinality** dimensions
+	* (e.g. `Command` adds `requested_by.kind`). Keep values bounded — they
+	* become metric label values, so a user id or free-form string here would
+	* explode the metric's cardinality. Defaults to none.
+	*/
+	spanAttributes(_input) {
+		return {};
+	}
+	async runInstrumented(input, observability) {
+		const { logger, metrics, tracer } = observability;
+		const name = this.useCaseName;
+		const attributes = safely(() => this.spanAttributes(input)) ?? {};
+		const span = safely(() => tracer?.startSpan(name, {
+			"use_case.name": name,
+			...attributes
+		}));
+		const startedAt = performance.now();
+		let outcome = "exception";
+		try {
+			const output = await this.execute(input);
+			outcome = output.isOk() ? "ok" : "error";
+			if (outcome === "error") {
+				const code = businessErrorCode(output);
+				safely(() => logger?.warn(`${name} returned a business error`, {
+					useCase: name,
+					...code ? { code } : {}
+				}));
+			}
+			safely(() => span?.setAttribute("use_case.outcome", outcome));
+			safely(() => metrics?.counter(EXECUTION_COUNTER, 1, {
+				useCase: name,
+				outcome,
+				...attributes
+			}));
+			return output;
+		} catch (error) {
+			safely(() => logger?.error(`${name} threw an unexpected error`, { useCase: name }));
+			safely(() => span?.setAttribute("use_case.outcome", "exception"));
+			safely(() => span?.recordException(error));
+			safely(() => metrics?.counter(EXECUTION_COUNTER, 1, {
+				useCase: name,
+				outcome: "exception",
+				...attributes
+			}));
+			throw error;
+		} finally {
+			safely(() => metrics?.histogram(DURATION_HISTOGRAM, performance.now() - startedAt, {
+				useCase: name,
+				outcome,
+				...attributes
+			}));
+			safely(() => span?.end());
+		}
+	}
+};
+UseCase = __decorate([version("1.0")], UseCase);
+/**
+* Pulls the stable `code` off a business-error `Result` for logging. Returns
+* `undefined` when the error is not an {@link AppError} — the code is safe to
+* log (it's the public contract), unlike the message which may carry PII.
+*/
+function businessErrorCode(output) {
+	const error = output.errorOrNull();
+	return error instanceof AppError ? error.code : void 0;
+}
+/**
+* Invokes an observability side effect, isolating any adapter failure so it
+* cannot alter the use case outcome.
+*/
+function safely(effect) {
+	try {
+		return effect();
+	} catch {
+		return;
+	}
+}
+//#endregion
 //#region src/core/application/commands/command.ts
 /**
 * Base for use cases that **mutate state** (writes), following CQS.
@@ -14,7 +134,17 @@ import { t as assertValidDate } from "./temporal-guards.js";
 * 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 {};
+let Command = class Command extends UseCase {
+	/**
+	* Surfaces the actor's *kind* (`"user"` / `"system"`) on the span and
+	* metrics so a write can be sliced by origin. Only the low-cardinality
+	* `kind` is emitted — never the raw id, which would blow up label
+	* cardinality and could leak a user identifier into metrics.
+	*/
+	spanAttributes(input) {
+		return { "requested_by.kind": input.requestedBy.kind };
+	}
+};
 Command = __decorate([version("1.0")], Command);
 //#endregion
 //#region src/core/application/policy-error-mapper.ts
@@ -36,11 +166,14 @@ function mapPolicyEvaluationError(err) {
 			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
-		} });
+		case "ENGINE_FAILURE": return new UnexpectedError(err.message, err.cause, {
+			publicMessage: "Policy evaluation failed unexpectedly.",
+			metadata: {
+				policyKey: err.policyKey,
+				engine: err.engine,
+				engineVersion: err.engineVersion
+			}
+		});
 	}
 }
 //#endregion
@@ -59,6 +192,11 @@ function mapPolicyEvaluationError(err) {
 * and safe to call multiple times with the same input.
 */
 let Query = class Query extends UseCase {
+	/**
+	* Declares how infrastructure should cache this query's result. Public so
+	* a caching adapter can actually read it off the instance; overrides must
+	* stay public.
+	*/
 	cacheStrategy() {
 		return { kind: "NO_CACHE" };
 	}
@@ -84,21 +222,35 @@ function createTemporalContext(input = {}) {
 }
 //#endregion
 //#region src/core/application/temporal/temporal-use-case.ts
-var TemporalUseCase = class extends UseCase {
+let TemporalUseCase = class TemporalUseCase extends UseCase {
 	resolveTemporalContext(input) {
 		return createTemporalContext(input.temporalContext);
 	}
+	/**
+	* Enriches a policy `ContextSeed` with `fields.now`, taken from the
+	* context's `requestedAt` (wall-clock time of the request).
+	*
+	* NOTE: this injects **only** `now` (from `requestedAt`) — it does *not*
+	* propagate `temporalContext.asOf`. Policy evaluation derives its own
+	* `asOf` from whichever seed field the policy's `asOfSource` points at
+	* (via `fields.now` by default). So a retroactive use case (an `asOf` in
+	* the past) will still evaluate policies at the *current* time unless the
+	* author maps `temporalContext.asOf` onto that seed field explicitly. Do
+	* that mapping in the use case when back-dated evaluation is intended.
+	*/
 	buildPolicySeed(seed, temporalContext) {
+		const fields = Object.freeze({
+			...seed.fields,
+			now: new Date(temporalContext.requestedAt.getTime())
+		});
 		return Object.freeze({
 			...seed,
-			fields: {
-				...seed.fields,
-				now: new Date(temporalContext.requestedAt.getTime())
-			}
+			fields
 		});
 	}
 };
+TemporalUseCase = __decorate([version("1.0")], TemporalUseCase);
 //#endregion
-export { mapPolicyEvaluationError as a, Query as i, assertTemporalContext as n, Command as o, createTemporalContext as r, TemporalUseCase as t };
+export { mapPolicyEvaluationError as a, Query as i, assertTemporalContext as n, Command as o, createTemporalContext as r, UseCase as s, TemporalUseCase as t };
 
 //# sourceMappingURL=temporal-use-case.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"temporal-use-case.js","names":[],"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,gBAGL,QAAuB,CAAC;sBAJjC,QAAQ,KAAK,CAAA,GAAA,OAAA;;;ACZd,SAAgB,yBAAyB,KAAsC;CAC3E,QAAQ,IAAI,MAAZ;EACI,KAAK,mBACD,OAAO,IAAI,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,IAAI,2BACP,sBACA,IAAI,SACJ,EAAE,cAAc,IAAI,aAAa,GACjC,EAAE,OAAO,IAAI,MAAM,CACvB;EACJ,KAAK,oBACD,OAAO,IAAI,cACP,UACA,EAAE,WAAW,IAAI,UAAU,GAC3B,EAAE,OAAO,IAAI,MAAM,CACvB;EACJ,KAAK,+BACD,OAAO,IAAI,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,IAAI,cACP,iBACA;GACI,WAAW,IAAI;GACf,YAAY,IAAI;GAChB,sBAAsB,IAAI;EAC9B,GACA,EAAE,OAAO,IAAI,MAAM,CACvB;EACJ,KAAK,kBACD,OAAO,IAAI,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,cAIL,QAAsC;CAC5C,gBAAyC;EACrC,OAAO,EAAE,MAAM,WAAW;CAC9B;AACJ;oBATC,QAAQ,KAAK,CAAA,GAAA,KAAA;;;AC3Bd,SAAS,sBACL,iBACA,YAAoB,mBAChB;CACJ,gBAAgB,GAAG,UAAU,QAAQ,gBAAgB,IAAI;CACzD,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,OAAO,cAAc;EACjB;EACA;CACJ,CAAC;AACL;;;ACNA,IAAe,kBAAf,cAGU,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"}
+{"version":3,"file":"temporal-use-case.js","names":[],"sources":["../src/core/application/use-case.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 { type ContractVersion, version } from \"../versioning/version.js\";\nimport { AppError } from \"../errors/index.js\";\nimport type { Result } from \"../result/result.js\";\n\nimport type { LoggerPort } from \"./ports/logger.port.js\";\nimport type { MetricsPort } from \"./ports/metrics.port.js\";\nimport type { TraceAttributeValue, TracerPort } from \"./ports/tracer.port.js\";\n\ntype MaybePromise<T> = T | Promise<T>;\n\n/**\n * Observability adapters a use case may opt into.\n *\n * All fields are optional: a use case that provides none keeps the plain\n * `input → Result` behavior with zero overhead. When provided, {@link UseCase.run}\n * instruments every execution around `execute()` — opening a span, recording\n * duration, counting outcomes, and logging business/unexpected failures.\n */\ninterface UseCaseObservability {\n    readonly logger?: LoggerPort;\n    readonly metrics?: MetricsPort;\n    readonly tracer?: TracerPort;\n}\n\nconst EXECUTION_COUNTER = \"use_case.executions\";\nconst DURATION_HISTOGRAM = \"use_case.duration_ms\";\n\ntype ExecutionOutcome = \"ok\" | \"error\" | \"exception\";\n\n@version(\"1.0\")\nabstract class UseCase<\n    Input = void,\n    Output extends Result<unknown, unknown> = Result<void, never>,\n> {\n    declare public static readonly CONTRACT_VERSION: ContractVersion;\n\n    public get contractVersion(): ContractVersion {\n        return (this.constructor as typeof UseCase).CONTRACT_VERSION;\n    }\n\n    /**\n     * Runs the use case.\n     *\n     * `run()` is the single seam every use case crosses, so it is where\n     * cross-cutting instrumentation lives. When {@link observability} exposes\n     * any adapter, the call to `execute()` is wrapped with tracing, metrics and\n     * failure logging; otherwise it delegates directly with no overhead.\n     *\n     * Observability is strictly side-effecting: a misbehaving adapter never\n     * changes the business result nor masks a thrown error — its own failures\n     * are swallowed.\n     */\n    public async run(input: Input): Promise<Output> {\n        const observability = this.observability();\n        if (\n            !observability.logger &&\n            !observability.metrics &&\n            !observability.tracer\n        ) {\n            return await this.execute(input);\n        }\n\n        return await this.runInstrumented(input, observability);\n    }\n\n    /**\n     * Adapters used to instrument {@link run}. Override to opt a use case into\n     * tracing/metrics/logging. Returns an empty object by default, which keeps\n     * the plain delegating behavior.\n     */\n    protected observability(): UseCaseObservability {\n        return {};\n    }\n\n    /**\n     * Stable identity used for span names and metric labels. Defaults to the\n     * runtime class name; override when bundling/minification would otherwise\n     * erase a meaningful name.\n     */\n    protected get useCaseName(): string {\n        return this.constructor.name;\n    }\n\n    protected abstract execute(input: Input): MaybePromise<Output>;\n\n    /**\n     * Extra attributes stamped onto the span and every metric emitted for this\n     * execution. Override to attach stable, **low-cardinality** dimensions\n     * (e.g. `Command` adds `requested_by.kind`). Keep values bounded — they\n     * become metric label values, so a user id or free-form string here would\n     * explode the metric's cardinality. Defaults to none.\n     */\n    protected spanAttributes(\n        _input: Input,\n    ): Readonly<Record<string, TraceAttributeValue>> {\n        return {};\n    }\n\n    private async runInstrumented(\n        input: Input,\n        observability: UseCaseObservability,\n    ): Promise<Output> {\n        const { logger, metrics, tracer } = observability;\n        const name = this.useCaseName;\n        const attributes = safely(() => this.spanAttributes(input)) ?? {};\n        const span = safely(() =>\n            tracer?.startSpan(name, { \"use_case.name\": name, ...attributes }),\n        );\n        const startedAt = performance.now();\n        // Declared here (not inside `try`) so the `finally` histogram can label\n        // duration by outcome; defaults to \"exception\" and is overwritten once\n        // execute() returns without throwing.\n        let outcome: ExecutionOutcome = \"exception\";\n\n        try {\n            const output = await this.execute(input);\n            outcome = output.isOk() ? \"ok\" : \"error\";\n\n            if (outcome === \"error\") {\n                const code = businessErrorCode(output);\n                safely(() =>\n                    logger?.warn(`${name} returned a business error`, {\n                        useCase: name,\n                        ...(code ? { code } : {}),\n                    }),\n                );\n            }\n            safely(() => span?.setAttribute(\"use_case.outcome\", outcome));\n            safely(() =>\n                metrics?.counter(EXECUTION_COUNTER, 1, {\n                    useCase: name,\n                    outcome,\n                    ...attributes,\n                }),\n            );\n\n            return output;\n        } catch (error) {\n            safely(() =>\n                logger?.error(`${name} threw an unexpected error`, {\n                    useCase: name,\n                }),\n            );\n            safely(() => span?.setAttribute(\"use_case.outcome\", \"exception\"));\n            safely(() => span?.recordException(error));\n            safely(() =>\n                metrics?.counter(EXECUTION_COUNTER, 1, {\n                    useCase: name,\n                    outcome: \"exception\",\n                    ...attributes,\n                }),\n            );\n\n            throw error;\n        } finally {\n            safely(() =>\n                metrics?.histogram(\n                    DURATION_HISTOGRAM,\n                    performance.now() - startedAt,\n                    { useCase: name, outcome, ...attributes },\n                ),\n            );\n            safely(() => span?.end());\n        }\n    }\n}\n\n/**\n * Pulls the stable `code` off a business-error `Result` for logging. Returns\n * `undefined` when the error is not an {@link AppError} — the code is safe to\n * log (it's the public contract), unlike the message which may carry PII.\n */\nfunction businessErrorCode(\n    output: Result<unknown, unknown>,\n): string | undefined {\n    const error = output.errorOrNull();\n    return error instanceof AppError ? error.code : undefined;\n}\n\n/**\n * Invokes an observability side effect, isolating any adapter failure so it\n * cannot alter the use case outcome.\n */\nfunction safely<R>(effect: () => R): R | undefined {\n    try {\n        return effect();\n    } catch {\n        return undefined;\n    }\n}\n\nexport { type MaybePromise, UseCase, type UseCaseObservability };\n","import { UseCase } from \"../use-case.js\";\nimport { version } from \"../../versioning/version.js\";\nimport type { TraceAttributeValue } from \"../ports/tracer.port.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    /**\n     * Surfaces the actor's *kind* (`\"user\"` / `\"system\"`) on the span and\n     * metrics so a write can be sliced by origin. Only the low-cardinality\n     * `kind` is emitted — never the raw id, which would blow up label\n     * cardinality and could leak a user identifier into metrics.\n     */\n    protected override spanAttributes(\n        input: Input,\n    ): Readonly<Record<string, TraceAttributeValue>> {\n        return { \"requested_by.kind\": input.requestedBy.kind };\n    }\n}\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            // `engine`/`engineVersion` are internal detail kept in `metadata`\n            // for logs. `publicMessage` gives the HTTP boundary a safe string\n            // to expose so it never has to serialize this metadata to a client\n            // on a 500. (Whether the boundary leaks `metadata` is still its\n            // call — this only hands it the non-leaking alternative.)\n            return new UnexpectedError(err.message, err.cause, {\n                publicMessage: \"Policy evaluation failed unexpectedly.\",\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 (offset-based).\n * Use as `Output` when the query returns a collection with pagination metadata.\n * For cursor/keyset pagination, model your own `Output` type instead.\n */\ninterface Page<T> {\n    readonly items: readonly T[];\n    /** Total rows across all pages, ignoring `page`/`pageSize`. */\n    readonly total: number;\n    /** 1-based page number (the first page is `1`, not `0`). */\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 *\n * These are pure descriptors: the type cannot enforce that a duration is finite\n * and positive, so the caching adapter must validate `ttlMs` /\n * `staleWhileRevalidateMs` (`> 0`, finite) before honoring the strategy.\n */\ntype CacheStrategy =\n    | { readonly kind: \"NO_CACHE\" }\n    | { readonly kind: \"TIME_TO_LIVE\"; readonly ttlMs: number }\n    | {\n          readonly kind: \"STALE_WHILE_REVALIDATE\";\n          /** How long the entry is served fresh. */\n          readonly ttlMs: number;\n          /**\n           * How long *after* `ttlMs` a stale entry may still be served while a\n           * background refresh runs. SWR needs both windows; a single TTL is\n           * ambiguous and each adapter would guess the second one.\n           */\n          readonly staleWhileRevalidateMs: number;\n      };\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    /**\n     * Declares how infrastructure should cache this query's result. Public so\n     * a caching adapter can actually read it off the instance; overrides must\n     * stay public.\n     */\n    public 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 { version } from \"../../versioning/version.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\n/**\n * Marker mixed into a temporal use case's `Input`.\n *\n * The consumer's `Input` must not re-declare `temporalContext` with an\n * incompatible type: `TemporalUseCase` intersects the two, and a clashing\n * declaration collapses the field to `never` (surfacing only as a confusing\n * error at the call site, not here).\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\n@version(\"1.0\")\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    /**\n     * Enriches a policy `ContextSeed` with `fields.now`, taken from the\n     * context's `requestedAt` (wall-clock time of the request).\n     *\n     * NOTE: this injects **only** `now` (from `requestedAt`) — it does *not*\n     * propagate `temporalContext.asOf`. Policy evaluation derives its own\n     * `asOf` from whichever seed field the policy's `asOfSource` points at\n     * (via `fields.now` by default). So a retroactive use case (an `asOf` in\n     * the past) will still evaluate policies at the *current* time unless the\n     * author maps `temporalContext.asOf` onto that seed field explicitly. Do\n     * that mapping in the use case when back-dated evaluation is intended.\n     */\n    protected buildPolicySeed<TSeed extends ContextSeed>(\n        seed: TSeed,\n        temporalContext: TemporalContext,\n    ): TemporalizedContextSeed<TSeed> {\n        // ponytail: shallow-freeze the two objects we create (outer + fields);\n        // nested `fields` values belong to the caller's seed — not ours to\n        // deep-freeze (would freeze shared refs) or structuredClone (would\n        // flatten any class instances the seed carries).\n        const fields = Object.freeze({\n            ...seed.fields,\n            now: new Date(temporalContext.requestedAt.getTime()),\n        });\n        return Object.freeze({\n            ...seed,\n            fields,\n        }) as TemporalizedContextSeed<TSeed>;\n    }\n}\n\nexport type { TemporalizedContextSeed, TemporalUseCaseInput };\nexport { TemporalUseCase };\n"],"mappings":"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"}

package/dist/unexpected-error.cjs

@@ -3,9 +3,11 @@ const require_app_error = require("./app-error.cjs");
 var UnexpectedError = class extends require_app_error.AppError {
 	constructor(message = "Unexpected error", cause, options) {
 		super(message, require_app_error.ErrorCodes.unexpected, {
-			cause,
-			...options
+			severity: "critical",
+			...options,
+			cause
 		});
+		Object.freeze(this);
 	}
 };
 //#endregion

package/dist/unexpected-error.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"unexpected-error.cjs","names":["AppError","ErrorCodes"],"sources":["../src/core/errors/unexpected-error.ts"],"sourcesContent":["import { AppError } from \"./app-error.js\";\nimport { ErrorCodes } from \"./error-codes.js\";\nimport type { AppErrorOptions } from \"./types.js\";\n\n// ─────────────────────────────────────────────────────────────────────────────\n// UnexpectedError\n// ─────────────────────────────────────────────────────────────────────────────\n\nclass UnexpectedError extends AppError {\n    constructor(\n        message = \"Unexpected error\",\n        cause?: unknown,\n        options?: Omit<AppErrorOptions, \"cause\">,\n    ) {\n        super(message, ErrorCodes.unexpected, {\n            cause,\n            ...options,\n        });\n    }\n}\n\nexport { UnexpectedError };\n"],"mappings":";;AAQA,IAAM,kBAAN,cAA8BA,kBAAAA,SAAS;CACnC,YACI,UAAU,oBACV,OACA,SACF;EACE,MAAM,SAASC,kBAAAA,WAAW,YAAY;GAClC;GACA,GAAG;EACP,CAAC;CACL;AACJ"}
+{"version":3,"file":"unexpected-error.cjs","names":["AppError","ErrorCodes"],"sources":["../src/core/errors/unexpected-error.ts"],"sourcesContent":["import { AppError } from \"./app-error.js\";\nimport { ErrorCodes } from \"./error-codes.js\";\nimport type { AppErrorOptions } from \"./types.js\";\n\n// ─────────────────────────────────────────────────────────────────────────────\n// UnexpectedError\n// ─────────────────────────────────────────────────────────────────────────────\n\nclass UnexpectedError extends AppError {\n    constructor(\n        message = \"Unexpected error\",\n        cause?: unknown,\n        options?: Omit<AppErrorOptions, \"cause\">,\n    ) {\n        // The error you most want alerted on defaults to \"critical\" — a caller\n        // can still lower it via options.severity.\n        super(message, ErrorCodes.unexpected, {\n            severity: \"critical\",\n            ...options,\n            cause,\n        });\n        Object.freeze(this);\n    }\n}\n\nexport { UnexpectedError };\n"],"mappings":";;AAQA,IAAM,kBAAN,cAA8BA,kBAAAA,SAAS;CACnC,YACI,UAAU,oBACV,OACA,SACF;EAGE,MAAM,SAASC,kBAAAA,WAAW,YAAY;GAClC,UAAU;GACV,GAAG;GACH;EACJ,CAAC;EACD,OAAO,OAAO,IAAI;CACtB;AACJ"}

package/dist/unexpected-error.js

@@ -3,9 +3,11 @@ import { r as ErrorCodes, t as AppError } from "./app-error.js";
 var UnexpectedError = class extends AppError {
 	constructor(message = "Unexpected error", cause, options) {
 		super(message, ErrorCodes.unexpected, {
-			cause,
-			...options
+			severity: "critical",
+			...options,
+			cause
 		});
+		Object.freeze(this);
 	}
 };
 //#endregion

package/dist/unexpected-error.js.map

@@ -1 +1 @@
-{"version":3,"file":"unexpected-error.js","names":[],"sources":["../src/core/errors/unexpected-error.ts"],"sourcesContent":["import { AppError } from \"./app-error.js\";\nimport { ErrorCodes } from \"./error-codes.js\";\nimport type { AppErrorOptions } from \"./types.js\";\n\n// ─────────────────────────────────────────────────────────────────────────────\n// UnexpectedError\n// ─────────────────────────────────────────────────────────────────────────────\n\nclass UnexpectedError extends AppError {\n    constructor(\n        message = \"Unexpected error\",\n        cause?: unknown,\n        options?: Omit<AppErrorOptions, \"cause\">,\n    ) {\n        super(message, ErrorCodes.unexpected, {\n            cause,\n            ...options,\n        });\n    }\n}\n\nexport { UnexpectedError };\n"],"mappings":";;AAQA,IAAM,kBAAN,cAA8B,SAAS;CACnC,YACI,UAAU,oBACV,OACA,SACF;EACE,MAAM,SAAS,WAAW,YAAY;GAClC;GACA,GAAG;EACP,CAAC;CACL;AACJ"}
+{"version":3,"file":"unexpected-error.js","names":[],"sources":["../src/core/errors/unexpected-error.ts"],"sourcesContent":["import { AppError } from \"./app-error.js\";\nimport { ErrorCodes } from \"./error-codes.js\";\nimport type { AppErrorOptions } from \"./types.js\";\n\n// ─────────────────────────────────────────────────────────────────────────────\n// UnexpectedError\n// ─────────────────────────────────────────────────────────────────────────────\n\nclass UnexpectedError extends AppError {\n    constructor(\n        message = \"Unexpected error\",\n        cause?: unknown,\n        options?: Omit<AppErrorOptions, \"cause\">,\n    ) {\n        // The error you most want alerted on defaults to \"critical\" — a caller\n        // can still lower it via options.severity.\n        super(message, ErrorCodes.unexpected, {\n            severity: \"critical\",\n            ...options,\n            cause,\n        });\n        Object.freeze(this);\n    }\n}\n\nexport { UnexpectedError };\n"],"mappings":";;AAQA,IAAM,kBAAN,cAA8B,SAAS;CACnC,YACI,UAAU,oBACV,OACA,SACF;EAGE,MAAM,SAAS,WAAW,YAAY;GAClC,UAAU;GACV,GAAG;GACH;EACJ,CAAC;EACD,OAAO,OAAO,IAAI;CACtB;AACJ"}

package/dist/uuid-identifier.cjs

@@ -1,11 +1,136 @@
+const require_invariant_violation_exception = require("./invariant-violation-exception.cjs");
+const require_temporal_guards = require("./temporal-guards.cjs");
+const require_immutable = require("./immutable.cjs");
+const require_decorate = require("./decorate.cjs");
+const require_uuid = require("./uuid.cjs");
+const require_aggregate_version = require("./aggregate-version.cjs");
 const require_value_object = require("./value-object.cjs");
-//#region src/core/domain/uuid-identifier.ts
+//#region src/core/domain/entity.ts
 /**
-* Canonical RFC-4122 UUID (versions 1–5), matched case-insensitively. Declared
-* once here so the dozens of typed identifiers a domain accumulates never have
-* to re-state the pattern.
+* Base class for domain entities — objects defined by a stable identity rather
+* than by their attributes. Two entities are "the same" when their `id`
+* matches, even if every other field differs; this is the opposite of a
+* {@link ValueObject}, which is defined entirely by its contents.
+*
+* The class owns the bookkeeping common to every aggregate root: a creation
+* timestamp that never changes, a last-modified timestamp, and an
+* `aggregateVersion` counter used for optimistic concurrency control. All three
+* are validated on construction and the dates are defensively cloned, so an
+* entity can never be built into — or leak — an inconsistent temporal state.
+*
+* @typeParam TIdentifier - The identity type (e.g. a branded string id or a VO).
 */
-const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+let Entity = class Entity {
+	/**
+	* Reconstitutes an entity from its persisted {@link EntityState}.
+	*
+	* Validates the temporal invariants up front so an invalid entity is
+	* impossible to construct: both dates must be valid, the aggregate version
+	* must be a non-negative integer, and `updatedAt` may not predate
+	* `createdAt`. Both dates are cloned on the way in so a later mutation of
+	* the caller's `Date` objects cannot reach into the entity's internal state.
+	*
+	* Declared `protected` because entities are reconstituted through a
+	* subclass factory, never instantiated directly by application code.
+	*
+	* @throws {InvariantViolationException} When `id` is absent, or when
+	*   `updatedAt` is earlier than `createdAt`.
+	*/
+	constructor(state) {
+		if (state.id == null) throw new require_invariant_violation_exception.InvariantViolationException("id is required: an entity cannot exist without an identity");
+		require_temporal_guards.assertValidDate("createdAt", state.createdAt);
+		require_temporal_guards.assertValidDate("updatedAt", state.updatedAt);
+		require_aggregate_version.assertValidAggregateVersion(state.aggregateVersion);
+		if (state.updatedAt.getTime() < state.createdAt.getTime()) throw new require_invariant_violation_exception.InvariantViolationException("updatedAt cannot be earlier than createdAt");
+		this._id = state.id;
+		this._createdAt = require_temporal_guards.cloneDate(state.createdAt);
+		this._updatedAt = require_temporal_guards.cloneDate(state.updatedAt);
+		this._aggregateVersion = state.aggregateVersion;
+	}
+	/** The entity's stable identity — the basis for equality between entities. */
+	get id() {
+		return this._id;
+	}
+	/**
+	* When the entity was first created.
+	*
+	* Returns a clone so callers cannot mutate the entity's internal `Date`;
+	* the value is fixed at construction and never changes thereafter.
+	*/
+	get createdAt() {
+		return require_temporal_guards.cloneDate(this._createdAt);
+	}
+	/**
+	* When the entity was last modified.
+	*
+	* Returns a clone for the same encapsulation reason as {@link createdAt};
+	* the underlying value advances only through {@link markAsModified}.
+	*/
+	get updatedAt() {
+		return require_temporal_guards.cloneDate(this._updatedAt);
+	}
+	/**
+	* Monotonic counter incremented on every mutation, used for optimistic
+	* concurrency control: a writer reads this value, and the persistence layer
+	* rejects the write if the stored version has moved on in the meantime.
+	*/
+	get aggregateVersion() {
+		return this._aggregateVersion;
+	}
+	/**
+	* The schema/contract version stamped on this entity type by the
+	* `@version` decorator — used to detect and migrate state persisted under
+	* an older shape.
+	*/
+	get contractVersion() {
+		return this.constructor.CONTRACT_VERSION;
+	}
+	/**
+	* The single seam through which an entity records a mutation: it advances
+	* `updatedAt` and bumps {@link aggregateVersion} by one. Subclasses must
+	* call this from every state-changing method so the version counter stays
+	* an accurate optimistic-lock token.
+	*
+	* `updatedAt` is monotonic: each call must be at or after the current
+	* `updatedAt` (equal is fine — two mutations can share a millisecond).
+	* Without this, the version counter would advance while the timestamp
+	* walked backwards, corrupting any audit trail or ordering that reads
+	* `updatedAt`. A caller replaying out-of-order events must sort them first.
+	*
+	* @param updatedAt - The modification instant; defaults to now.
+	* @returns The new aggregate version after the increment.
+	* @throws {InvariantViolationException} When `updatedAt` is earlier than
+	*   the current `updatedAt`.
+	*/
+	markAsModified(updatedAt = /* @__PURE__ */ new Date()) {
+		require_temporal_guards.assertValidDate("updatedAt", updatedAt);
+		if (updatedAt.getTime() < this._updatedAt.getTime()) throw new require_invariant_violation_exception.InvariantViolationException("updatedAt cannot move backwards: it must be at or after the current updatedAt");
+		this._updatedAt = require_temporal_guards.cloneDate(updatedAt);
+		this._aggregateVersion += 1;
+		return this._aggregateVersion;
+	}
+	/**
+	* Identity-based equality — the semantics that define an entity. Two
+	* entities are equal when they are the same concrete class and their ids
+	* match, regardless of any other field.
+	*
+	* The class check keeps a `CustomerId`-bearing entity from equalling an
+	* unrelated entity that happens to reuse the same raw id. Value-object ids
+	* are compared through their own `equals`, so two independently
+	* reconstituted id instances still match; primitive ids use `===`.
+	*/
+	equals(other) {
+		if (other == null) return false;
+		if (other === this) return true;
+		if (other.constructor !== this.constructor) return false;
+		const id = this._id;
+		if (id instanceof require_value_object.ValueObject) return id.equals(other._id);
+		return this._id === other._id;
+	}
+};
+Entity = require_decorate.__decorate([require_immutable.version("1.0")], Entity);
+//#endregion
+//#region src/core/domain/uuid-identifier.ts
 /**
 * Base class for UUID-backed identity value objects.
 *
@@ -47,14 +172,22 @@ var UuidIdentifier = class extends require_value_object.ValueObject {
 		return this.value;
 	}
 	/**
-	* Whether `candidate` is a canonical UUID (versions 1–5). The single source
-	* of truth for the format; concrete identifiers call this from `create`.
+	* Whether `candidate` is a canonical UUID (versions 1–8, including the
+	* time-ordered v7; nil and max UUIDs are rejected as sentinels). The single
+	* source of truth for the format — see `shared/uuid.ts`; concrete
+	* identifiers call this from `create`.
 	*/
 	static isValid(candidate) {
-		return UUID_PATTERN.test(candidate);
+		return require_uuid.UUID_PATTERN.test(candidate);
 	}
 };
 //#endregion
+Object.defineProperty(exports, "Entity", {
+	enumerable: true,
+	get: function() {
+		return Entity;
+	}
+});
 Object.defineProperty(exports, "UuidIdentifier", {
 	enumerable: true,
 	get: function() {

package/dist/uuid-identifier.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"uuid-identifier.cjs","names":["ValueObject"],"sources":["../src/core/domain/uuid-identifier.ts"],"sourcesContent":["import { ValueObject } from \"./value-object.js\";\n\n/**\n * Canonical RFC-4122 UUID (versions 1–5), matched case-insensitively. Declared\n * once here so the dozens of typed identifiers a domain accumulates never have\n * to re-state the pattern.\n */\nconst UUID_PATTERN =\n    /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;\n\n/**\n * Base class for UUID-backed identity value objects.\n *\n * A domain typically has many of these — `OrderId`, `CustomerId`, `InvoiceId` —\n * all wrapping the same `string` shape. Two problems follow: the UUID format\n * check gets copy-pasted into every one, and because the wrapped shape is\n * identical, TypeScript's structural typing would happily accept an `OrderId`\n * where a `CustomerId` is expected. `UuidIdentifier` solves both: the format\n * lives here once ({@link isValid}), and the `TBrand` phantom tag makes each\n * subtype nominally distinct so the ids cannot be swapped for one another.\n *\n * It deliberately does not impose a factory. Identifiers vary in how they\n * report an invalid value (their own exception type, their own message), so a\n * concrete id adds a validating `create` that calls {@link isValid} plus a\n * `reconstitute` that trusts an already-persisted value:\n *\n * ```ts\n * class OrderId extends UuidIdentifier<\"OrderId\"> {\n *   private constructor(value: string) { super(value); }\n *   static create(raw: string): OrderId {\n *     if (!UuidIdentifier.isValid(raw)) throw new InvalidOrderIdError(raw);\n *     return new OrderId(raw);\n *   }\n *   static reconstitute(value: string): OrderId { return new OrderId(value); }\n * }\n * ```\n *\n * @typeParam TBrand - A unique string literal that nominally tags the subtype.\n */\nabstract class UuidIdentifier<\n    TBrand extends string = string,\n> extends ValueObject<string, string> {\n    /**\n     * Phantom brand. Never assigned at runtime (`declare`), it exists only so\n     * two identifiers with different brands are not interchangeable at the type\n     * level despite sharing the same `string` value.\n     */\n    protected declare readonly __brand: TBrand;\n\n    protected constructor(value: string) {\n        super(value);\n    }\n\n    public toPrimitive(): string {\n        return this.value;\n    }\n\n    /** The wrapped UUID string — convenient for logging and interpolation. */\n    public toString(): string {\n        return this.value;\n    }\n\n    /**\n     * Whether `candidate` is a canonical UUID (versions 1–5). The single source\n     * of truth for the format; concrete identifiers call this from `create`.\n     */\n    public static isValid(candidate: string): boolean {\n        return UUID_PATTERN.test(candidate);\n    }\n}\n\nexport { UuidIdentifier };\n"],"mappings":";;;;;;;AAOA,MAAM,eACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BJ,IAAe,iBAAf,cAEUA,qBAAAA,YAA4B;CAQlC,YAAsB,OAAe;EACjC,MAAM,KAAK;CACf;CAEA,cAA6B;EACzB,OAAO,KAAK;CAChB;;CAGA,WAA0B;EACtB,OAAO,KAAK;CAChB;;;;;CAMA,OAAc,QAAQ,WAA4B;EAC9C,OAAO,aAAa,KAAK,SAAS;CACtC;AACJ"}
+{"version":3,"file":"uuid-identifier.cjs","names":["InvariantViolationException","cloneDate","ValueObject","version","ValueObject","UUID_PATTERN"],"sources":["../src/core/domain/entity.ts","../src/core/domain/uuid-identifier.ts"],"sourcesContent":["import { InvariantViolationException } from \"../exceptions/invariant-violation-exception.js\";\nimport { assertValidAggregateVersion } from \"../shared/aggregate-version.js\";\nimport { assertValidDate, cloneDate } from \"../shared/temporal-guards.js\";\nimport { type ContractVersion, version } from \"../versioning/version.js\";\n\nimport { ValueObject } from \"./value-object.js\";\n\n/**\n * The minimal persisted shape needed to reconstitute an {@link Entity}.\n *\n * This is the contract between storage and the domain: a repository maps a row\n * (or document) onto these four fields and hands them to a subclass constructor.\n * `aggregateVersion` travels with the state so optimistic-concurrency checks\n * survive a round-trip through the database.\n */\ninterface EntityState<TIdentifier> {\n    readonly id: TIdentifier;\n    readonly createdAt: Date;\n    readonly updatedAt: Date;\n    readonly aggregateVersion: number;\n}\n\n/**\n * Base class for domain entities — objects defined by a stable identity rather\n * than by their attributes. Two entities are \"the same\" when their `id`\n * matches, even if every other field differs; this is the opposite of a\n * {@link ValueObject}, which is defined entirely by its contents.\n *\n * The class owns the bookkeeping common to every aggregate root: a creation\n * timestamp that never changes, a last-modified timestamp, and an\n * `aggregateVersion` counter used for optimistic concurrency control. All three\n * are validated on construction and the dates are defensively cloned, so an\n * entity can never be built into — or leak — an inconsistent temporal state.\n *\n * @typeParam TIdentifier - The identity type (e.g. a branded string id or a VO).\n */\n@version(\"1.0\")\nabstract class Entity<TIdentifier> {\n    declare public static readonly CONTRACT_VERSION: ContractVersion;\n\n    private readonly _id: TIdentifier;\n    private readonly _createdAt: Date;\n    private _updatedAt: Date;\n    private _aggregateVersion: number;\n\n    /**\n     * Reconstitutes an entity from its persisted {@link EntityState}.\n     *\n     * Validates the temporal invariants up front so an invalid entity is\n     * impossible to construct: both dates must be valid, the aggregate version\n     * must be a non-negative integer, and `updatedAt` may not predate\n     * `createdAt`. Both dates are cloned on the way in so a later mutation of\n     * the caller's `Date` objects cannot reach into the entity's internal state.\n     *\n     * Declared `protected` because entities are reconstituted through a\n     * subclass factory, never instantiated directly by application code.\n     *\n     * @throws {InvariantViolationException} When `id` is absent, or when\n     *   `updatedAt` is earlier than `createdAt`.\n     */\n    protected constructor(state: EntityState<TIdentifier>) {\n        if (state.id == null) {\n            throw new InvariantViolationException(\n                \"id is required: an entity cannot exist without an identity\",\n            );\n        }\n\n        assertValidDate(\"createdAt\", state.createdAt);\n        assertValidDate(\"updatedAt\", state.updatedAt);\n        assertValidAggregateVersion(state.aggregateVersion);\n\n        if (state.updatedAt.getTime() < state.createdAt.getTime()) {\n            throw new InvariantViolationException(\n                \"updatedAt cannot be earlier than createdAt\",\n            );\n        }\n\n        this._id = state.id;\n        this._createdAt = cloneDate(state.createdAt);\n        this._updatedAt = cloneDate(state.updatedAt);\n        this._aggregateVersion = state.aggregateVersion;\n    }\n\n    /** The entity's stable identity — the basis for equality between entities. */\n    public get id(): TIdentifier {\n        return this._id;\n    }\n\n    /**\n     * When the entity was first created.\n     *\n     * Returns a clone so callers cannot mutate the entity's internal `Date`;\n     * the value is fixed at construction and never changes thereafter.\n     */\n    public get createdAt(): Date {\n        return cloneDate(this._createdAt);\n    }\n\n    /**\n     * When the entity was last modified.\n     *\n     * Returns a clone for the same encapsulation reason as {@link createdAt};\n     * the underlying value advances only through {@link markAsModified}.\n     */\n    public get updatedAt(): Date {\n        return cloneDate(this._updatedAt);\n    }\n\n    /**\n     * Monotonic counter incremented on every mutation, used for optimistic\n     * concurrency control: a writer reads this value, and the persistence layer\n     * rejects the write if the stored version has moved on in the meantime.\n     */\n    public get aggregateVersion(): number {\n        return this._aggregateVersion;\n    }\n\n    /**\n     * The schema/contract version stamped on this entity type by the\n     * `@version` decorator — used to detect and migrate state persisted under\n     * an older shape.\n     */\n    public get contractVersion(): ContractVersion {\n        return (this.constructor as typeof Entity).CONTRACT_VERSION;\n    }\n\n    /**\n     * The single seam through which an entity records a mutation: it advances\n     * `updatedAt` and bumps {@link aggregateVersion} by one. Subclasses must\n     * call this from every state-changing method so the version counter stays\n     * an accurate optimistic-lock token.\n     *\n     * `updatedAt` is monotonic: each call must be at or after the current\n     * `updatedAt` (equal is fine — two mutations can share a millisecond).\n     * Without this, the version counter would advance while the timestamp\n     * walked backwards, corrupting any audit trail or ordering that reads\n     * `updatedAt`. A caller replaying out-of-order events must sort them first.\n     *\n     * @param updatedAt - The modification instant; defaults to now.\n     * @returns The new aggregate version after the increment.\n     * @throws {InvariantViolationException} When `updatedAt` is earlier than\n     *   the current `updatedAt`.\n     */\n    protected markAsModified(updatedAt: Date = new Date()): number {\n        assertValidDate(\"updatedAt\", updatedAt);\n\n        if (updatedAt.getTime() < this._updatedAt.getTime()) {\n            throw new InvariantViolationException(\n                \"updatedAt cannot move backwards: it must be at or after the current updatedAt\",\n            );\n        }\n\n        this._updatedAt = cloneDate(updatedAt);\n        this._aggregateVersion += 1;\n\n        return this._aggregateVersion;\n    }\n\n    /**\n     * Identity-based equality — the semantics that define an entity. Two\n     * entities are equal when they are the same concrete class and their ids\n     * match, regardless of any other field.\n     *\n     * The class check keeps a `CustomerId`-bearing entity from equalling an\n     * unrelated entity that happens to reuse the same raw id. Value-object ids\n     * are compared through their own `equals`, so two independently\n     * reconstituted id instances still match; primitive ids use `===`.\n     */\n    public equals(other: Entity<TIdentifier> | null | undefined): boolean {\n        if (other == null) {\n            return false;\n        }\n        if (other === this) {\n            return true;\n        }\n        if (other.constructor !== this.constructor) {\n            return false;\n        }\n\n        const id: unknown = this._id;\n        if (id instanceof ValueObject) {\n            return id.equals(other._id as typeof id);\n        }\n\n        return this._id === other._id;\n    }\n}\n\nexport { Entity, type EntityState };\n","import { UUID_PATTERN } from \"../shared/uuid.js\";\nimport { ValueObject } from \"./value-object.js\";\n\n/**\n * Base class for UUID-backed identity value objects.\n *\n * A domain typically has many of these — `OrderId`, `CustomerId`, `InvoiceId` —\n * all wrapping the same `string` shape. Two problems follow: the UUID format\n * check gets copy-pasted into every one, and because the wrapped shape is\n * identical, TypeScript's structural typing would happily accept an `OrderId`\n * where a `CustomerId` is expected. `UuidIdentifier` solves both: the format\n * lives here once ({@link isValid}), and the `TBrand` phantom tag makes each\n * subtype nominally distinct so the ids cannot be swapped for one another.\n *\n * It deliberately does not impose a factory. Identifiers vary in how they\n * report an invalid value (their own exception type, their own message), so a\n * concrete id adds a validating `create` that calls {@link isValid} plus a\n * `reconstitute` that trusts an already-persisted value:\n *\n * ```ts\n * class OrderId extends UuidIdentifier<\"OrderId\"> {\n *   private constructor(value: string) { super(value); }\n *   static create(raw: string): OrderId {\n *     if (!UuidIdentifier.isValid(raw)) throw new InvalidOrderIdError(raw);\n *     return new OrderId(raw);\n *   }\n *   static reconstitute(value: string): OrderId { return new OrderId(value); }\n * }\n * ```\n *\n * @typeParam TBrand - A unique string literal that nominally tags the subtype.\n */\nabstract class UuidIdentifier<\n    TBrand extends string = string,\n> extends ValueObject<string, string> {\n    /**\n     * Phantom brand. Never assigned at runtime (`declare`), it exists only so\n     * two identifiers with different brands are not interchangeable at the type\n     * level despite sharing the same `string` value.\n     */\n    declare protected readonly __brand: TBrand;\n\n    protected constructor(value: string) {\n        super(value);\n    }\n\n    public toPrimitive(): string {\n        return this.value;\n    }\n\n    /** The wrapped UUID string — convenient for logging and interpolation. */\n    public toString(): string {\n        return this.value;\n    }\n\n    /**\n     * Whether `candidate` is a canonical UUID (versions 1–8, including the\n     * time-ordered v7; nil and max UUIDs are rejected as sentinels). The single\n     * source of truth for the format — see `shared/uuid.ts`; concrete\n     * identifiers call this from `create`.\n     */\n    public static isValid(candidate: string): boolean {\n        return UUID_PATTERN.test(candidate);\n    }\n}\n\nexport { UuidIdentifier };\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAoCA,IAAA,SAAA,MACe,OAAoB;;;;;;;;;;;;;;;;CAuB/B,YAAsB,OAAiC;EACnD,IAAI,MAAM,MAAM,MACZ,MAAM,IAAIA,sCAAAA,4BACN,4DACJ;EAGJ,wBAAA,gBAAgB,aAAa,MAAM,SAAS;EAC5C,wBAAA,gBAAgB,aAAa,MAAM,SAAS;EAC5C,0BAAA,4BAA4B,MAAM,gBAAgB;EAElD,IAAI,MAAM,UAAU,QAAQ,IAAI,MAAM,UAAU,QAAQ,GACpD,MAAM,IAAIA,sCAAAA,4BACN,4CACJ;EAGJ,KAAK,MAAM,MAAM;EACjB,KAAK,aAAaC,wBAAAA,UAAU,MAAM,SAAS;EAC3C,KAAK,aAAaA,wBAAAA,UAAU,MAAM,SAAS;EAC3C,KAAK,oBAAoB,MAAM;CACnC;;CAGA,IAAW,KAAkB;EACzB,OAAO,KAAK;CAChB;;;;;;;CAQA,IAAW,YAAkB;EACzB,OAAOA,wBAAAA,UAAU,KAAK,UAAU;CACpC;;;;;;;CAQA,IAAW,YAAkB;EACzB,OAAOA,wBAAAA,UAAU,KAAK,UAAU;CACpC;;;;;;CAOA,IAAW,mBAA2B;EAClC,OAAO,KAAK;CAChB;;;;;;CAOA,IAAW,kBAAmC;EAC1C,OAAQ,KAAK,YAA8B;CAC/C;;;;;;;;;;;;;;;;;;CAmBA,eAAyB,4BAAkB,IAAI,KAAK,GAAW;EAC3D,wBAAA,gBAAgB,aAAa,SAAS;EAEtC,IAAI,UAAU,QAAQ,IAAI,KAAK,WAAW,QAAQ,GAC9C,MAAM,IAAID,sCAAAA,4BACN,+EACJ;EAGJ,KAAK,aAAaC,wBAAAA,UAAU,SAAS;EACrC,KAAK,qBAAqB;EAE1B,OAAO,KAAK;CAChB;;;;;;;;;;;CAYA,OAAc,OAAwD;EAClE,IAAI,SAAS,MACT,OAAO;EAEX,IAAI,UAAU,MACV,OAAO;EAEX,IAAI,MAAM,gBAAgB,KAAK,aAC3B,OAAO;EAGX,MAAM,KAAc,KAAK;EACzB,IAAI,cAAcC,qBAAAA,aACd,OAAO,GAAG,OAAO,MAAM,GAAgB;EAG3C,OAAO,KAAK,QAAQ,MAAM;CAC9B;AACJ;sCAtJCC,kBAAAA,QAAQ,KAAK,CAAA,GAAA,MAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACJd,IAAe,iBAAf,cAEUC,qBAAAA,YAA4B;CAQlC,YAAsB,OAAe;EACjC,MAAM,KAAK;CACf;CAEA,cAA6B;EACzB,OAAO,KAAK;CAChB;;CAGA,WAA0B;EACtB,OAAO,KAAK;CAChB;;;;;;;CAQA,OAAc,QAAQ,WAA4B;EAC9C,OAAOC,aAAAA,aAAa,KAAK,SAAS;CACtC;AACJ"}

package/dist/uuid-identifier.d.cts

@@ -49,7 +49,8 @@ declare abstract class Entity<TIdentifier> {
    * Declared `protected` because entities are reconstituted through a
    * subclass factory, never instantiated directly by application code.
    *
-   * @throws {InvariantViolationException} When `updatedAt` is earlier than `createdAt`.
+   * @throws {InvariantViolationException} When `id` is absent, or when
+   *   `updatedAt` is earlier than `createdAt`.
    */
   protected constructor(state: EntityState<TIdentifier>);
   /** The entity's stable identity — the basis for equality between entities. */
@@ -86,13 +87,29 @@ declare abstract class Entity<TIdentifier> {
    * call this from every state-changing method so the version counter stays
    * an accurate optimistic-lock token.
    *
-   * @param updatedAt - The modification instant; defaults to now. Validated
-   *   and required not to predate `createdAt`, preserving the same invariant
-   *   the constructor enforces.
+   * `updatedAt` is monotonic: each call must be at or after the current
+   * `updatedAt` (equal is fine — two mutations can share a millisecond).
+   * Without this, the version counter would advance while the timestamp
+   * walked backwards, corrupting any audit trail or ordering that reads
+   * `updatedAt`. A caller replaying out-of-order events must sort them first.
+   *
+   * @param updatedAt - The modification instant; defaults to now.
    * @returns The new aggregate version after the increment.
-   * @throws {InvariantViolationException} When `updatedAt` is earlier than `createdAt`.
+   * @throws {InvariantViolationException} When `updatedAt` is earlier than
+   *   the current `updatedAt`.
    */
   protected markAsModified(updatedAt?: Date): number;
+  /**
+   * Identity-based equality — the semantics that define an entity. Two
+   * entities are equal when they are the same concrete class and their ids
+   * match, regardless of any other field.
+   *
+   * The class check keeps a `CustomerId`-bearing entity from equalling an
+   * unrelated entity that happens to reuse the same raw id. Value-object ids
+   * are compared through their own `equals`, so two independently
+   * reconstituted id instances still match; primitive ids use `===`.
+   */
+  equals(other: Entity<TIdentifier> | null | undefined): boolean;
 }
 //#endregion
 //#region src/core/domain/uuid-identifier.d.ts
@@ -137,8 +154,10 @@ declare abstract class UuidIdentifier<TBrand extends string = string> extends Va
   /** The wrapped UUID string — convenient for logging and interpolation. */
   toString(): string;
   /**
-   * Whether `candidate` is a canonical UUID (versions 1–5). The single source
-   * of truth for the format; concrete identifiers call this from `create`.
+   * Whether `candidate` is a canonical UUID (versions 1–8, including the
+   * time-ordered v7; nil and max UUIDs are rejected as sentinels). The single
+   * source of truth for the format — see `shared/uuid.ts`; concrete
+   * identifiers call this from `create`.
    */
   static isValid(candidate: string): boolean;
 }