@cullet/erp-core 1.0.11 → 1.2.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"temporal-use-case.js","names":[],"sources":["../src/core/application/commands/requested-by.ts","../src/core/application/commands/command.ts","../src/core/application/policy-error-mapper.ts","../src/core/application/queries/query.ts","../src/core/application/temporal/temporal-context.ts","../src/core/application/temporal/temporal-use-case.ts"],"sourcesContent":["import { ValidationCode } from \"../../exceptions/validation-code.js\";\nimport { InvalidValueException } from \"../../exceptions/validation-exception.js\";\nimport { ValidationField } from \"../../exceptions/validation-field.js\";\n\n// Identifies who triggered a Command.\n// Two valid formats:\n//   - Human user: UUID v4 (e.g.: \"550e8400-e29b-41d4-a716-446655440000\")\n//   - System identity: \"system:<job>\" where <job> is [a-z][a-z0-9]*(-[a-z0-9]+)*\n//     (e.g.: \"system:late-fee-job\", \"system:email-sender\")\n//\n// The split between `fromUser` / `fromSystem` / `parse` exists to make intent\n// explicit at the call-site: whoever builds the value knows where it came from.\n\ntype RequestedByKind = \"user\" | \"system\";\n\nconst REQUESTED_BY_FIELD = ValidationField.of(\"requestedBy\");\n\nconst UUID_PATTERN =\n    /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;\n\n// system:<job> where <job> starts with a lowercase letter and may have hyphens between segments\nconst SYSTEM_IDENTITY_PATTERN = /^system:[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;\n\nclass RequestedBy {\n    readonly kind: RequestedByKind;\n    readonly raw: string;\n\n    private constructor(kind: RequestedByKind, raw: string) {\n        this.kind = kind;\n        this.raw = raw;\n        Object.freeze(this);\n    }\n\n    /** Builds from a human user ID (must be a UUID). */\n    static fromUser(userId: string): RequestedBy {\n        if (!UUID_PATTERN.test(userId)) {\n            throw new InvalidValueException(\n                REQUESTED_BY_FIELD,\n                ValidationCode.INVALID_FORMAT,\n                `requestedBy: user identity must be a UUID, got \"${userId}\"`,\n            );\n        }\n\n        return new RequestedBy(\"user\", userId);\n    }\n\n    /**\n     * Builds from a system identity.\n     * Only accepts the format \"system:<job>\", where <job> matches [a-z][a-z0-9]*(-[a-z0-9]+)*.\n     */\n    static fromSystem(systemIdentity: string): RequestedBy {\n        if (!SYSTEM_IDENTITY_PATTERN.test(systemIdentity)) {\n            throw new InvalidValueException(\n                REQUESTED_BY_FIELD,\n                ValidationCode.INVALID_FORMAT,\n                `requestedBy: system identity must match \"system:<job>\" (e.g. \"system:late-fee-job\"), got \"${systemIdentity}\"`,\n            );\n        }\n\n        return new RequestedBy(\"system\", systemIdentity);\n    }\n\n    /**\n     * Infers the kind from the raw value.\n     * Use when the origin (user vs system) is not known at the call-site.\n     */\n    static parse(raw: string): RequestedBy {\n        if (UUID_PATTERN.test(raw)) {\n            return new RequestedBy(\"user\", raw);\n        }\n\n        if (SYSTEM_IDENTITY_PATTERN.test(raw)) {\n            return new RequestedBy(\"system\", raw);\n        }\n\n        throw new InvalidValueException(\n            REQUESTED_BY_FIELD,\n            ValidationCode.INVALID_FORMAT,\n            `requestedBy must be a UUID (user) or \"system:<job>\" (system), got \"${raw}\"`,\n        );\n    }\n\n    get isUser(): boolean {\n        return this.kind === \"user\";\n    }\n\n    get isSystem(): boolean {\n        return this.kind === \"system\";\n    }\n\n    toString(): string {\n        return this.raw;\n    }\n}\n\nexport type { RequestedByKind };\nexport { RequestedBy };\n","import { UseCase } from \"../use-case.js\";\nimport { version } from \"../../versioning/version.js\";\nimport type { Result } from \"../../result/result.js\";\n\nimport { RequestedBy } from \"./requested-by.js\";\n\ninterface CommandInput {\n    readonly requestedBy: RequestedBy;\n}\n\n/**\n * Base for use cases that **mutate state** (writes), following CQS.\n *\n * - `Input extends CommandInput` ensures every mutation records who triggered it.\n * - `Output extends Result<unknown, unknown>` ensures business errors are\n *   explicit values, never thrown exceptions.\n *\n * The Command/Query distinction is semantic: the type declares the intent\n * before any implementation exists, guiding code review and API contracts.\n */\n@version(\"1.0\")\nabstract class Command<\n    Input extends CommandInput,\n    Output extends Result<unknown, unknown> = Result<void, never>,\n> extends UseCase<Input, Output> {}\n\nexport type { CommandInput };\nexport { Command };\n","import {\n    type AppError,\n    BusinessRuleViolationError,\n    NotFoundError,\n    UnexpectedError,\n} from \"../errors/index.js\";\nimport type { PolicyEvaluationError } from \"../policies/index.js\";\n\nexport function mapPolicyEvaluationError(err: PolicyEvaluationError): AppError {\n    switch (err.kind) {\n        case \"INVALID_CONTEXT\":\n            return new BusinessRuleViolationError(\n                `policy.${err.stage.toLowerCase()}`,\n                err.message,\n                { policyKey: err.policyKey, stage: err.stage },\n                { cause: err.cause },\n            );\n        case \"INVALID_POLICY_KEY\":\n            return new BusinessRuleViolationError(\n                \"policy.invalid_key\",\n                err.message,\n                { rawPolicyKey: err.rawPolicyKey },\n                { cause: err.cause },\n            );\n        case \"POLICY_NOT_FOUND\":\n            return new NotFoundError(\n                \"Policy\",\n                { policyKey: err.policyKey },\n                { cause: err.cause },\n            );\n        case \"POLICY_DEFINITION_NOT_FOUND\":\n            return new NotFoundError(\n                \"PolicyDefinition\",\n                {\n                    policyKey: err.policyKey,\n                    contextVersion: err.contextVersion,\n                    asOf: err.asOf.toISOString(),\n                },\n                { cause: err.cause },\n            );\n        case \"POLICY_VARIANT_NOT_FOUND\":\n            return new NotFoundError(\n                \"PolicyVariant\",\n                {\n                    policyKey: err.policyKey,\n                    policyKind: err.policyKind,\n                    payloadSchemaVersion: err.payloadSchemaVersion,\n                },\n                { cause: err.cause },\n            );\n        case \"ENGINE_FAILURE\":\n            return new UnexpectedError(err.message, err.cause, {\n                metadata: {\n                    policyKey: err.policyKey,\n                    engine: err.engine,\n                    engineVersion: err.engineVersion,\n                },\n            });\n    }\n}\n","import { UseCase } from \"../use-case.js\";\nimport { version } from \"../../versioning/version.js\";\nimport type { AppError } from \"../../errors/index.js\";\nimport type { Result } from \"../../result/result.js\";\n\n/**\n * Paginated result of a list query.\n * Use as `Output` when the query returns a collection with pagination metadata.\n */\ninterface Page<T> {\n    readonly items: readonly T[];\n    readonly total: number;\n    readonly page: number;\n    readonly pageSize: number;\n}\n\n/**\n * Cache strategy declared by the query type.\n * Infrastructure reads this value to decide whether and how to cache the result.\n */\ntype CacheStrategy =\n    | { readonly kind: \"NO_CACHE\" }\n    | { readonly kind: \"TIME_TO_LIVE\"; readonly ttlMs: number }\n    | { readonly kind: \"STALE_WHILE_REVALIDATE\"; readonly ttlMs: number };\n\ntype QueryOutput = object | string | number | boolean | bigint | symbol | null;\n\n/**\n * Base for use cases that **only read state**, with no side effects, following CQS.\n *\n * - `Data extends QueryOutput` prevents a query from declaring a `void` or\n *   `undefined` success payload, while still allowing primitive projections\n *   and `null` when that makes sense for the read. Failures stay explicit in\n *   `Result<T, E>`.\n * - Override `cacheStrategy()` to declare how infrastructure should cache the\n *   result. By default, no cache is applied.\n *\n * A Query must never mutate persisted data — its execution must be idempotent\n * and safe to call multiple times with the same input.\n */\n@version(\"1.0\")\nabstract class Query<\n    Input = void,\n    Data extends QueryOutput = never,\n    Failure = AppError,\n> extends UseCase<Input, Result<Data, Failure>> {\n    protected cacheStrategy(): CacheStrategy {\n        return { kind: \"NO_CACHE\" };\n    }\n}\n\nexport type { CacheStrategy, Page, QueryOutput };\nexport { Query };\n","import { makeImmutable } from \"../../shared/immutable.js\";\nimport { assertValidDate } from \"../../shared/temporal-guards.js\";\n\ninterface TemporalContext {\n    readonly asOf: Date;\n    readonly requestedAt: Date;\n}\n\ninterface CreateTemporalContextInput {\n    readonly asOf?: Date;\n    readonly requestedAt?: Date;\n}\n\nfunction assertTemporalContext(\n    temporalContext: TemporalContext,\n    fieldName: string = \"temporalContext\",\n): void {\n    assertValidDate(`${fieldName}.asOf`, temporalContext.asOf);\n    assertValidDate(`${fieldName}.requestedAt`, temporalContext.requestedAt);\n}\n\nfunction createTemporalContext(\n    input: CreateTemporalContextInput = {},\n): TemporalContext {\n    const requestedAt = input.requestedAt ?? new Date();\n    const asOf = input.asOf ?? requestedAt;\n\n    assertTemporalContext({ asOf, requestedAt });\n\n    return makeImmutable({\n        asOf,\n        requestedAt,\n    });\n}\n\nexport {\n    assertTemporalContext,\n    createTemporalContext,\n    type CreateTemporalContextInput,\n    type TemporalContext,\n};\n","import { UseCase } from \"../use-case.js\";\nimport type { ContextSeed } from \"../../policies/index.js\";\nimport type { Result } from \"../../result/result.js\";\n\nimport {\n    createTemporalContext,\n    type TemporalContext,\n} from \"./temporal-context.js\";\n\ninterface TemporalUseCaseInput {\n    readonly temporalContext?: TemporalContext;\n}\n\n/**\n * A {@link ContextSeed} after temporal enrichment by\n * {@link TemporalUseCase.buildPolicySeed}: structurally identical to `TSeed`,\n * except `fields.now` is now guaranteed present as a `Date` (injected from the\n * resolved {@link TemporalContext}). Downstream policies can therefore read\n * `seed.fields.now` without a presence/type guard.\n */\ntype TemporalizedContextSeed<TSeed extends ContextSeed> = Omit<\n    TSeed,\n    \"fields\"\n> & {\n    readonly fields: TSeed[\"fields\"] & { readonly now: Date };\n};\n\nabstract class TemporalUseCase<\n    Input extends object,\n    Output extends Result<unknown, unknown>,\n> extends UseCase<Input & TemporalUseCaseInput, Output> {\n    protected resolveTemporalContext(\n        input: Input & TemporalUseCaseInput,\n    ): TemporalContext {\n        return createTemporalContext(input.temporalContext);\n    }\n\n    protected buildPolicySeed<TSeed extends ContextSeed>(\n        seed: TSeed,\n        temporalContext: TemporalContext,\n    ): TemporalizedContextSeed<TSeed> {\n        return Object.freeze({\n            ...seed,\n            fields: {\n                ...seed.fields,\n                now: new Date(temporalContext.requestedAt.getTime()),\n            },\n        }) as TemporalizedContextSeed<TSeed>;\n    }\n}\n\nexport type { TemporalizedContextSeed, TemporalUseCaseInput };\nexport { TemporalUseCase };\n"],"mappings":"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"}

package/dist/unexpected-error.js

@@ -0,0 +1,179 @@
+//#region src/core/errors/error-codes.ts
+const ErrorCodes = {
+	authentication: {
+		missingToken: "sec.authn.missing_token",
+		invalidToken: "sec.authn.invalid_token",
+		expiredToken: "sec.authn.expired_token",
+		invalidCredentials: "sec.authn.invalid_credentials"
+	},
+	authorization: {
+		forbidden: "sec.authz.forbidden",
+		policyDenied: "sec.authz.policy_denied",
+		missingCapability: "sec.authz.missing_capability",
+		outOfScope: "sec.authz.out_of_scope"
+	},
+	businessRuleViolation: "business_rule_violation",
+	conflict: {
+		alreadyExists: "conf.already_exists",
+		duplicate: "conf.duplicate",
+		uniqueViolation: "conf.unique_violation"
+	},
+	idempotency: {
+		keyMissing: "idemp.key_missing",
+		inProgress: "idemp.in_progress",
+		payloadMismatch: "idemp.payload_mismatch",
+		replayNotSupported: "idemp.replay_not_supported"
+	},
+	integration: {
+		timeout: "int.timeout",
+		unreachable: "int.unreachable",
+		badResponse: "int.bad_response"
+	},
+	legacyIncompatible: "legacy_incompatible",
+	notFound: "not_found",
+	serialization: {
+		deserializePrefix: "ser.des",
+		serializePrefix: "ser.ser"
+	},
+	temporal: {
+		expired: "tmp.expired",
+		notYetValid: "tmp.not_yet_valid"
+	},
+	unexpected: "unexpected",
+	validation: "validation_error"
+};
+function serializationErrorCode(direction, category) {
+	return `${direction === "deserialize" ? ErrorCodes.serialization.deserializePrefix : ErrorCodes.serialization.serializePrefix}.${category}`;
+}
+//#endregion
+//#region src/core/errors/utils/json-safe.ts
+const NON_SERIALIZABLE_PLACEHOLDER = "[NonSerializable]";
+const CIRCULAR_REFERENCE_PLACEHOLDER = "[Circular]";
+function isPlainObject(value) {
+	if (value === null || typeof value !== "object") return false;
+	const proto = Object.getPrototypeOf(value);
+	return proto === Object.prototype || proto === null;
+}
+function sanitizeValue(value, seen) {
+	if (value === null) return null;
+	const type = typeof value;
+	if (type === "string" || type === "number" || type === "boolean") return value;
+	if (type === "bigint" || type === "function" || type === "symbol" || value === void 0) return NON_SERIALIZABLE_PLACEHOLDER;
+	if (Array.isArray(value)) {
+		if (seen.has(value)) return CIRCULAR_REFERENCE_PLACEHOLDER;
+		seen.add(value);
+		const sanitized = value.map((item) => sanitizeValue(item, seen));
+		seen.delete(value);
+		return sanitized;
+	}
+	if (value instanceof Date) return NON_SERIALIZABLE_PLACEHOLDER;
+	if (!isPlainObject(value)) return NON_SERIALIZABLE_PLACEHOLDER;
+	if (seen.has(value)) return CIRCULAR_REFERENCE_PLACEHOLDER;
+	seen.add(value);
+	const result = {};
+	for (const [key, val] of Object.entries(value)) result[key] = sanitizeValue(val, seen);
+	seen.delete(value);
+	return result;
+}
+/**
+* Ensures metadata is JSON-serializable.
+*
+* **Allowed:** string, number, boolean, null, arrays, and plain objects.
+*
+* **Converted to placeholder:** Date, BigInt, class instances, functions,
+* symbols, undefined, and circular references (which would otherwise make
+* `JSON.stringify` throw).
+*
+* @throws {TypeError} If `input` is not a plain object at the root level.
+*/
+function assertJsonSafeMetadata(input) {
+	if (input === void 0) return {};
+	if (!isPlainObject(input)) throw new TypeError("metadata must be a plain object (Record<string, unknown>).");
+	return sanitizeValue(input, /* @__PURE__ */ new WeakSet());
+}
+//#endregion
+//#region src/core/errors/app-error.ts
+/**
+* Root of the application/domain error hierarchy. Every error the system raises
+* on purpose extends `AppError`, which gives callers a single `instanceof` to
+* catch and a uniform, serializable shape to log and transport.
+*
+* Beyond the native `Error` message it carries a stable `code` (the contract the
+* outside world matches on), an optional non-leaking `publicMessage`, a
+* severity, JSON-safe `metadata`, and the correlation/request/command ids that
+* stitch an error back to the request that produced it. The metadata is
+* validated as JSON-safe on construction, so a logger can serialize any
+* `AppError` without hitting a circular reference or a non-serializable value.
+*
+* Abstract on purpose: callers should throw a specific subclass (e.g.
+* {@link ValidationError}, {@link NotFoundError}) so the `code` and shape are
+* meaningful, never a bare `AppError`.
+*/
+var AppError = class extends Error {
+	/**
+	* Builds the common error envelope shared by every subclass.
+	*
+	* `name` is taken from `new.target` so the thrown instance reports its
+	* concrete subclass name (not `"AppError"`), and the prototype is re-pinned
+	* via `setPrototypeOf` so `instanceof` keeps working after transpilation to
+	* older targets where extending built-ins breaks the chain. `createdAtIso`
+	* defaults to now, and `metadata` is validated as JSON-safe so the error is
+	* always serializable.
+	*
+	* Declared `protected`: instantiate a concrete subclass, never `AppError`.
+	*
+	* @param message - The internal, developer-facing message.
+	* @param code - The stable machine-readable code callers match on.
+	* @param options - Optional cause, metadata, severity, and correlation ids.
+	* @throws When `options.metadata` contains a value that is not JSON-safe.
+	*/
+	constructor(message, code, options) {
+		super(message);
+		this.name = new.target.name;
+		this.code = code;
+		this.cause = options?.cause;
+		this.type = options?.type;
+		this.severity = options?.severity;
+		this.correlationId = options?.correlationId;
+		this.requestId = options?.requestId;
+		this.commandId = options?.commandId;
+		this.createdAtIso = options?.createdAtIso ?? (/* @__PURE__ */ new Date()).toISOString();
+		this.publicMessage = options?.publicMessage;
+		this.metadata = options?.metadata ? assertJsonSafeMetadata(options.metadata) : void 0;
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
+	/**
+	* Returns a JSON-safe representation of the error.
+	* Does NOT include `cause` by default (to avoid leaking internal details).
+	*/
+	toJSON() {
+		const payload = {
+			name: this.name,
+			code: this.code,
+			message: this.message,
+			createdAtIso: this.createdAtIso
+		};
+		if (this.type !== void 0) payload.type = this.type;
+		if (this.severity !== void 0) payload.severity = this.severity;
+		if (this.publicMessage !== void 0) payload.publicMessage = this.publicMessage;
+		if (this.metadata !== void 0) payload.metadata = this.metadata;
+		if (this.correlationId !== void 0) payload.correlationId = this.correlationId;
+		if (this.requestId !== void 0) payload.requestId = this.requestId;
+		if (this.commandId !== void 0) payload.commandId = this.commandId;
+		return payload;
+	}
+};
+//#endregion
+//#region src/core/errors/unexpected-error.ts
+var UnexpectedError = class extends AppError {
+	constructor(message = "Unexpected error", cause, options) {
+		super(message, ErrorCodes.unexpected, {
+			cause,
+			...options
+		});
+	}
+};
+//#endregion
+export { serializationErrorCode as a, ErrorCodes as i, AppError as n, assertJsonSafeMetadata as r, UnexpectedError as t };
+
+//# sourceMappingURL=unexpected-error.js.map

package/dist/unexpected-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unexpected-error.js","names":[],"sources":["../src/core/errors/error-codes.ts","../src/core/errors/utils/json-safe.ts","../src/core/errors/app-error.ts","../src/core/errors/unexpected-error.ts"],"sourcesContent":["const ErrorCodes = {\n    authentication: {\n        missingToken: \"sec.authn.missing_token\",\n        invalidToken: \"sec.authn.invalid_token\",\n        expiredToken: \"sec.authn.expired_token\",\n        invalidCredentials: \"sec.authn.invalid_credentials\",\n    },\n    authorization: {\n        forbidden: \"sec.authz.forbidden\",\n        policyDenied: \"sec.authz.policy_denied\",\n        missingCapability: \"sec.authz.missing_capability\",\n        outOfScope: \"sec.authz.out_of_scope\",\n    },\n    businessRuleViolation: \"business_rule_violation\",\n    conflict: {\n        alreadyExists: \"conf.already_exists\",\n        duplicate: \"conf.duplicate\",\n        uniqueViolation: \"conf.unique_violation\",\n    },\n    idempotency: {\n        keyMissing: \"idemp.key_missing\",\n        inProgress: \"idemp.in_progress\",\n        payloadMismatch: \"idemp.payload_mismatch\",\n        replayNotSupported: \"idemp.replay_not_supported\",\n    },\n    integration: {\n        timeout: \"int.timeout\",\n        unreachable: \"int.unreachable\",\n        badResponse: \"int.bad_response\",\n    },\n    legacyIncompatible: \"legacy_incompatible\",\n    notFound: \"not_found\",\n    serialization: {\n        deserializePrefix: \"ser.des\",\n        serializePrefix: \"ser.ser\",\n    },\n    temporal: {\n        expired: \"tmp.expired\",\n        notYetValid: \"tmp.not_yet_valid\",\n    },\n    unexpected: \"unexpected\",\n    validation: \"validation_error\",\n} as const;\n\ntype SerializationCodeDirection = \"deserialize\" | \"serialize\";\n\nfunction serializationErrorCode(\n    direction: SerializationCodeDirection,\n    category: string,\n): string {\n    const prefix =\n        direction === \"deserialize\"\n            ? ErrorCodes.serialization.deserializePrefix\n            : ErrorCodes.serialization.serializePrefix;\n\n    return `${prefix}.${category}`;\n}\n\nexport { ErrorCodes, serializationErrorCode };\nexport type { SerializationCodeDirection };\n","// Utilities for ensuring metadata is JSON-serializable.\n\nimport type { JsonSafeRecord, JsonSafeValue } from \"../types.js\";\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Constants\n// ─────────────────────────────────────────────────────────────────────────────\n\nconst NON_SERIALIZABLE_PLACEHOLDER = \"[NonSerializable]\";\nconst CIRCULAR_REFERENCE_PLACEHOLDER = \"[Circular]\";\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Internal helpers\n// ─────────────────────────────────────────────────────────────────────────────\n\nfunction isPlainObject(value: unknown): value is Record<string, unknown> {\n    if (value === null || typeof value !== \"object\") return false;\n    const proto = Object.getPrototypeOf(value);\n    return proto === Object.prototype || proto === null;\n}\n\n// `seen` tracks the ancestors on the current traversal branch (a DFS path), not\n// every object visited. This collapses true circular references to a placeholder\n// while still serializing the same object referenced more than once across\n// sibling branches (a DAG) — matching `JSON.stringify`, which only rejects\n// cycles, not shared references.\nfunction sanitizeValue(value: unknown, seen: WeakSet<object>): JsonSafeValue {\n    // Null passthrough\n    if (value === null) return null;\n\n    const type = typeof value;\n\n    // Primitives\n    if (type === \"string\" || type === \"number\" || type === \"boolean\") {\n        return value as JsonSafeValue;\n    }\n\n    // Non-serializable primitives\n    if (\n        type === \"bigint\" ||\n        type === \"function\" ||\n        type === \"symbol\" ||\n        value === undefined\n    ) {\n        return NON_SERIALIZABLE_PLACEHOLDER;\n    }\n\n    // Arrays (recursive)\n    if (Array.isArray(value)) {\n        if (seen.has(value)) return CIRCULAR_REFERENCE_PLACEHOLDER;\n        seen.add(value);\n        const sanitized = value.map((item) => sanitizeValue(item, seen));\n        seen.delete(value);\n        return sanitized;\n    }\n\n    // Date → placeholder (could also use .toISOString() if preferred)\n    if (value instanceof Date) {\n        return NON_SERIALIZABLE_PLACEHOLDER;\n    }\n\n    // Class instances and non-plain objects → placeholder\n    if (!isPlainObject(value)) {\n        return NON_SERIALIZABLE_PLACEHOLDER;\n    }\n\n    // Plain object (recursive)\n    if (seen.has(value)) return CIRCULAR_REFERENCE_PLACEHOLDER;\n    seen.add(value);\n    const result: Record<string, JsonSafeValue> = {};\n    for (const [key, val] of Object.entries(value)) {\n        result[key] = sanitizeValue(val, seen);\n    }\n    seen.delete(value);\n    return result;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Public API\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Ensures metadata is JSON-serializable.\n *\n * **Allowed:** string, number, boolean, null, arrays, and plain objects.\n *\n * **Converted to placeholder:** Date, BigInt, class instances, functions,\n * symbols, undefined, and circular references (which would otherwise make\n * `JSON.stringify` throw).\n *\n * @throws {TypeError} If `input` is not a plain object at the root level.\n */\nfunction assertJsonSafeMetadata(input: unknown): JsonSafeRecord {\n    if (input === undefined) {\n        return {};\n    }\n\n    if (!isPlainObject(input)) {\n        throw new TypeError(\n            \"metadata must be a plain object (Record<string, unknown>).\",\n        );\n    }\n\n    return sanitizeValue(input, new WeakSet<object>()) as JsonSafeRecord;\n}\n\nexport {\n    assertJsonSafeMetadata,\n    CIRCULAR_REFERENCE_PLACEHOLDER,\n    NON_SERIALIZABLE_PLACEHOLDER,\n};\n","// Base application error for the domain/application layer.\n// Encapsulates a code, optional cause, and JSON-safe metadata.\n\nimport type {\n    AppErrorOptions,\n    ErrorSeverity,\n    JsonSafeRecord,\n} from \"./types.js\";\nimport { assertJsonSafeMetadata } from \"./utils/index.js\";\n\n// ─────────────────────────────────────────────────────────────────────────────\n// AppError (abstract base class)\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Root of the application/domain error hierarchy. Every error the system raises\n * on purpose extends `AppError`, which gives callers a single `instanceof` to\n * catch and a uniform, serializable shape to log and transport.\n *\n * Beyond the native `Error` message it carries a stable `code` (the contract the\n * outside world matches on), an optional non-leaking `publicMessage`, a\n * severity, JSON-safe `metadata`, and the correlation/request/command ids that\n * stitch an error back to the request that produced it. The metadata is\n * validated as JSON-safe on construction, so a logger can serialize any\n * `AppError` without hitting a circular reference or a non-serializable value.\n *\n * Abstract on purpose: callers should throw a specific subclass (e.g.\n * {@link ValidationError}, {@link NotFoundError}) so the `code` and shape are\n * meaningful, never a bare `AppError`.\n */\nabstract class AppError extends Error {\n    public readonly code: string;\n    public readonly cause?: unknown;\n    public readonly metadata?: JsonSafeRecord;\n    public readonly type?: string;\n    public readonly severity?: ErrorSeverity;\n    public readonly createdAtIso: string;\n    public readonly publicMessage?: string;\n    /**\n     * Identifies a single execution \"story\" in the system. All operations\n     * related to the same logical flow must share the same correlationId.\n     */\n    public readonly correlationId?: string;\n    /**\n     * Identifies a specific technical request attempt (each retry may produce\n     * a new requestId), even when the correlationId stays the same.\n     */\n    public readonly requestId?: string;\n    /**\n     * Marks the business intent / idempotency key; stays the same across\n     * technical retries and multiple requests that represent the same intent.\n     */\n    public readonly commandId?: string;\n\n    /**\n     * Builds the common error envelope shared by every subclass.\n     *\n     * `name` is taken from `new.target` so the thrown instance reports its\n     * concrete subclass name (not `\"AppError\"`), and the prototype is re-pinned\n     * via `setPrototypeOf` so `instanceof` keeps working after transpilation to\n     * older targets where extending built-ins breaks the chain. `createdAtIso`\n     * defaults to now, and `metadata` is validated as JSON-safe so the error is\n     * always serializable.\n     *\n     * Declared `protected`: instantiate a concrete subclass, never `AppError`.\n     *\n     * @param message - The internal, developer-facing message.\n     * @param code - The stable machine-readable code callers match on.\n     * @param options - Optional cause, metadata, severity, and correlation ids.\n     * @throws When `options.metadata` contains a value that is not JSON-safe.\n     */\n    protected constructor(\n        message: string,\n        code: string,\n        options?: AppErrorOptions,\n    ) {\n        super(message);\n\n        this.name = new.target.name;\n        this.code = code;\n        this.cause = options?.cause;\n        this.type = options?.type;\n        this.severity = options?.severity;\n        this.correlationId = options?.correlationId;\n        this.requestId = options?.requestId;\n        this.commandId = options?.commandId;\n        this.createdAtIso = options?.createdAtIso ?? new Date().toISOString();\n        this.publicMessage = options?.publicMessage;\n\n        this.metadata = options?.metadata\n            ? assertJsonSafeMetadata(options.metadata)\n            : undefined;\n\n        Object.setPrototypeOf(this, new.target.prototype);\n    }\n\n    /**\n     * Returns a JSON-safe representation of the error.\n     * Does NOT include `cause` by default (to avoid leaking internal details).\n     */\n    public toJSON(): Record<string, unknown> {\n        const payload: Record<string, unknown> = {\n            name: this.name,\n            code: this.code,\n            message: this.message,\n            createdAtIso: this.createdAtIso,\n        };\n\n        // Optional fields are emitted only when defined, so the serialized\n        // shape never carries `undefined`-valued keys (consistent with how the\n        // correlation/request/command ids are handled).\n        if (this.type !== undefined) payload.type = this.type;\n        if (this.severity !== undefined) payload.severity = this.severity;\n        if (this.publicMessage !== undefined)\n            payload.publicMessage = this.publicMessage;\n        if (this.metadata !== undefined) payload.metadata = this.metadata;\n        if (this.correlationId !== undefined)\n            payload.correlationId = this.correlationId;\n        if (this.requestId !== undefined) payload.requestId = this.requestId;\n        if (this.commandId !== undefined) payload.commandId = this.commandId;\n\n        return payload;\n    }\n}\n\nexport { AppError };\n","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":"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"}

package/dist/use-case.js

@@ -0,0 +1,91 @@
+import { i as version, n as __decorate } from "./immutable.js";
+//#region src/core/application/use-case.ts
+var _UseCase;
+const EXECUTION_COUNTER = "use_case.executions";
+const DURATION_HISTOGRAM = "use_case.duration_ms";
+let UseCase = class UseCase {
+	static {
+		_UseCase = this;
+	}
+	get contractVersion() {
+		return _UseCase.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;
+	}
+	async runInstrumented(input, observability) {
+		const { logger, metrics, tracer } = observability;
+		const name = this.useCaseName;
+		const span = safely(() => tracer?.startSpan(name, { "use_case.name": name }));
+		const startedAt = Date.now();
+		try {
+			const output = await this.execute(input);
+			const outcome = output.isOk() ? "ok" : "error";
+			if (outcome === "error") safely(() => logger?.warn(`${name} returned a business error`, { useCase: name }));
+			safely(() => span?.setAttribute("use_case.outcome", outcome));
+			safely(() => metrics?.counter(EXECUTION_COUNTER, 1, {
+				useCase: name,
+				outcome
+			}));
+			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"
+			}));
+			throw error;
+		} finally {
+			safely(() => metrics?.histogram(DURATION_HISTOGRAM, Date.now() - startedAt, { useCase: name }));
+			safely(() => span?.end());
+		}
+	}
+};
+UseCase = _UseCase = __decorate([version("1.0")], UseCase);
+/**
+* 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
+export { UseCase as t };
+
+//# sourceMappingURL=use-case.js.map

package/dist/use-case.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-case.js","names":[],"sources":["../src/core/application/use-case.ts"],"sourcesContent":["import { type ContractVersion, version } from \"../versioning/version.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 { 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 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    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 span = safely(() =>\n            tracer?.startSpan(name, { \"use_case.name\": name }),\n        );\n        const startedAt = Date.now();\n\n        try {\n            const output = await this.execute(input);\n            const outcome: ExecutionOutcome = output.isOk() ? \"ok\" : \"error\";\n\n            if (outcome === \"error\") {\n                safely(() =>\n                    logger?.warn(`${name} returned a business error`, {\n                        useCase: name,\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                }),\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                }),\n            );\n\n            throw error;\n        } finally {\n            safely(() =>\n                metrics?.histogram(DURATION_HISTOGRAM, Date.now() - startedAt, {\n                    useCase: name,\n                }),\n            );\n            safely(() => span?.end());\n        }\n    }\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"],"mappings":";;;AAuBA,MAAM,oBAAoB;AAC1B,MAAM,qBAAqB;AAI3B,IAAA,UAAA,MACe,QAGb;;;;CAGE,IAAW,kBAAmC;EAC1C,OAAA,SAAe;CACnB;;;;;;;;;;;;;CAcA,MAAa,IAAI,OAA+B;EAC5C,MAAM,gBAAgB,KAAK,cAAc;EACzC,IACI,CAAC,cAAc,UACf,CAAC,cAAc,WACf,CAAC,cAAc,QAEf,OAAO,MAAM,KAAK,QAAQ,KAAK;EAGnC,OAAO,MAAM,KAAK,gBAAgB,OAAO,aAAa;CAC1D;;;;;;CAOA,gBAAgD;EAC5C,OAAO,CAAC;CACZ;;;;;;CAOA,IAAc,cAAsB;EAChC,OAAO,KAAK,YAAY;CAC5B;CAIA,MAAc,gBACV,OACA,eACe;EACf,MAAM,EAAE,QAAQ,SAAS,WAAW;EACpC,MAAM,OAAO,KAAK;EAClB,MAAM,OAAO,aACT,QAAQ,UAAU,MAAM,EAAE,iBAAiB,KAAK,CAAC,CACrD;EACA,MAAM,YAAY,KAAK,IAAI;EAE3B,IAAI;GACA,MAAM,SAAS,MAAM,KAAK,QAAQ,KAAK;GACvC,MAAM,UAA4B,OAAO,KAAK,IAAI,OAAO;GAEzD,IAAI,YAAY,SACZ,aACI,QAAQ,KAAK,GAAG,KAAK,6BAA6B,EAC9C,SAAS,KACb,CAAC,CACL;GAEJ,aAAa,MAAM,aAAa,oBAAoB,OAAO,CAAC;GAC5D,aACI,SAAS,QAAQ,mBAAmB,GAAG;IACnC,SAAS;IACT;GACJ,CAAC,CACL;GAEA,OAAO;EACX,SAAS,OAAO;GACZ,aACI,QAAQ,MAAM,GAAG,KAAK,6BAA6B,EAC/C,SAAS,KACb,CAAC,CACL;GACA,aAAa,MAAM,aAAa,oBAAoB,WAAW,CAAC;GAChE,aAAa,MAAM,gBAAgB,KAAK,CAAC;GACzC,aACI,SAAS,QAAQ,mBAAmB,GAAG;IACnC,SAAS;IACT,SAAS;GACb,CAAC,CACL;GAEA,MAAM;EACV,UAAU;GACN,aACI,SAAS,UAAU,oBAAoB,KAAK,IAAI,IAAI,WAAW,EAC3D,SAAS,KACb,CAAC,CACL;GACA,aAAa,MAAM,IAAI,CAAC;EAC5B;CACJ;AACJ;iCAhHC,QAAQ,KAAK,CAAA,GAAA,OAAA;;;;;AAsHd,SAAS,OAAU,QAAgC;CAC/C,IAAI;EACA,OAAO,OAAO;CAClB,QAAQ;EACJ;CACJ;AACJ"}

package/dist/uuid-identifier.d.ts

@@ -0,0 +1,230 @@
+import { n as ContractVersion } from "./version.js";
+import { t as DeepReadonly } from "./immutable.js";
+import { t as PluginManager } from "./plugin.js";
+
+//#region src/core/domain/entity.d.ts
+
+/**
+ * The minimal persisted shape needed to reconstitute an {@link Entity}.
+ *
+ * This is the contract between storage and the domain: a repository maps a row
+ * (or document) onto these four fields and hands them to a subclass constructor.
+ * `aggregateVersion` travels with the state so optimistic-concurrency checks
+ * survive a round-trip through the database.
+ */
+interface EntityState<TIdentifier> {
+  readonly id: TIdentifier;
+  readonly createdAt: Date;
+  readonly updatedAt: Date;
+  readonly aggregateVersion: number;
+}
+/**
+ * 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).
+ */
+declare abstract class Entity<TIdentifier> {
+  static readonly CONTRACT_VERSION: ContractVersion;
+  private readonly _id;
+  private readonly _createdAt;
+  private _updatedAt;
+  private _aggregateVersion;
+  /**
+   * 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 `updatedAt` is earlier than `createdAt`.
+   */
+  protected constructor(state: EntityState<TIdentifier>);
+  /** The entity's stable identity — the basis for equality between entities. */
+  get id(): TIdentifier;
+  /**
+   * 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(): Date;
+  /**
+   * 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(): Date;
+  /**
+   * 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(): number;
+  /**
+   * 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(): ContractVersion;
+  /**
+   * 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.
+   *
+   * @param updatedAt - The modification instant; defaults to now. Validated
+   *   and required not to predate `createdAt`, preserving the same invariant
+   *   the constructor enforces.
+   * @returns The new aggregate version after the increment.
+   * @throws {InvariantViolationException} When `updatedAt` is earlier than `createdAt`.
+   */
+  protected markAsModified(updatedAt?: Date): number;
+}
+//#endregion
+//#region src/core/domain/value-object.d.ts
+/**
+ * Extension point for value-object equality. A plugin implementing this
+ * contract overrides how any two value objects are compared, letting the host
+ * application swap in a structural comparator (e.g. `lodash.isEqual` over the
+ * wrapped `value`) without every value object having to implement `equals` by
+ * hand.
+ */
+type ValueObjectPluginContract = {
+  equals: (a: ValueObject<unknown, unknown>, b: ValueObject<unknown, unknown>) => boolean;
+};
+/**
+ * Base class for value objects — domain concepts defined entirely by their
+ * contents, with no identity of their own. Two value objects are
+ * interchangeable when they hold equal data, which is the opposite of an
+ * {@link Entity} (compared by id). Money, a CPF, a date range: replacing one
+ * instance with an equal one changes nothing about the model.
+ *
+ * Immutability is the defining guarantee here. The wrapped `value` is
+ * deep-frozen on construction, so a value object can be shared freely without
+ * any risk of a consumer mutating shared state. Subclasses seal the instance
+ * itself with {@link finalize} once their own fields are set.
+ *
+ * @typeParam T - The shape of the wrapped data.
+ * @typeParam P - The primitive form produced by {@link toPrimitive} / {@link toJSON}.
+ */
+declare abstract class ValueObject<T, P> {
+  static readonly CONTRACT_VERSION: ContractVersion;
+  /**
+   * Registry of equality plugins shared by every value object. Empty by
+   * default — when nothing is registered, {@link equals} falls back to a
+   * structural comparison of the wrapped `value`. Hosts register a plugin
+   * (e.g. `lodash.isEqual`) once at startup to customise equality globally.
+   */
+  static readonly plugins: PluginManager<ValueObjectPluginContract>;
+  /** The wrapped data, deep-frozen so it can never be mutated after construction. */
+  readonly value: DeepReadonly<T>;
+  /**
+   * Wraps `value`, deep-freezing it so the value object is immutable from the
+   * moment it exists. Declared `protected` because value objects are built
+   * through a validating subclass factory, never instantiated directly.
+   */
+  protected constructor(value: T);
+  /**
+   * The schema/contract version stamped on this value-object type by the
+   * `@version` decorator — used to detect state persisted under an older shape.
+   */
+  get contractVersion(): ContractVersion;
+  /**
+   * Freezes the instance shell, blocking reassignment of any own field.
+   *
+   * `value` is already deep-frozen by the constructor, so the wrapped data is
+   * immutable regardless. The instance itself is NOT frozen automatically
+   * because a subclass may still need to assign its own fields after
+   * `super(value)` runs. Call `finalize()` at the very end of the subclass
+   * constructor (after all fields are set) to make the whole value object
+   * immutable.
+   */
+  protected finalize(): void;
+  /**
+   * Hook for `JSON.stringify`. Delegates to {@link toPrimitive} so a value
+   * object serializes to its primitive form rather than exposing the internal
+   * `value` wrapper.
+   */
+  toJSON(): P;
+  /**
+   * Compares this value object with another by content. Because value objects
+   * carry no identity, two independently constructed instances holding the
+   * same data are considered equal.
+   *
+   * Delegates to the registered equality {@link plugins}; with no plugin
+   * registered it falls back to comparing the serialized wrapped `value`.
+   * Subclasses may still override for a faster or domain-specific comparison.
+   */
+  equals(other: this): boolean;
+  /**
+   * Projects the value object down to a plain, serializable primitive form —
+   * the representation suitable for persistence, transport, or comparison.
+   */
+  abstract toPrimitive(): P;
+}
+//#endregion
+//#region src/core/domain/uuid-identifier.d.ts
+/**
+ * Base class for UUID-backed identity value objects.
+ *
+ * A domain typically has many of these — `OrderId`, `CustomerId`, `InvoiceId` —
+ * all wrapping the same `string` shape. Two problems follow: the UUID format
+ * check gets copy-pasted into every one, and because the wrapped shape is
+ * identical, TypeScript's structural typing would happily accept an `OrderId`
+ * where a `CustomerId` is expected. `UuidIdentifier` solves both: the format
+ * lives here once ({@link isValid}), and the `TBrand` phantom tag makes each
+ * subtype nominally distinct so the ids cannot be swapped for one another.
+ *
+ * It deliberately does not impose a factory. Identifiers vary in how they
+ * report an invalid value (their own exception type, their own message), so a
+ * concrete id adds a validating `create` that calls {@link isValid} plus a
+ * `reconstitute` that trusts an already-persisted value:
+ *
+ * ```ts
+ * class OrderId extends UuidIdentifier<"OrderId"> {
+ *   private constructor(value: string) { super(value); }
+ *   static create(raw: string): OrderId {
+ *     if (!UuidIdentifier.isValid(raw)) throw new InvalidOrderIdError(raw);
+ *     return new OrderId(raw);
+ *   }
+ *   static reconstitute(value: string): OrderId { return new OrderId(value); }
+ * }
+ * ```
+ *
+ * @typeParam TBrand - A unique string literal that nominally tags the subtype.
+ */
+declare abstract class UuidIdentifier<TBrand extends string = string> extends ValueObject<string, string> {
+  /**
+   * Phantom brand. Never assigned at runtime (`declare`), it exists only so
+   * two identifiers with different brands are not interchangeable at the type
+   * level despite sharing the same `string` value.
+   */
+  protected readonly __brand: TBrand;
+  protected constructor(value: string);
+  toPrimitive(): string;
+  /** 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`.
+   */
+  static isValid(candidate: string): boolean;
+}
+//#endregion
+export { EntityState as a, Entity as i, ValueObject as n, ValueObjectPluginContract as r, UuidIdentifier as t };
+//# sourceMappingURL=uuid-identifier.d.ts.map

package/dist/uuid-identifier.js

@@ -0,0 +1,60 @@
+import { t as ValueObject } from "./value-object.js";
+//#region src/core/domain/uuid-identifier.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.
+*/
+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;
+/**
+* Base class for UUID-backed identity value objects.
+*
+* A domain typically has many of these — `OrderId`, `CustomerId`, `InvoiceId` —
+* all wrapping the same `string` shape. Two problems follow: the UUID format
+* check gets copy-pasted into every one, and because the wrapped shape is
+* identical, TypeScript's structural typing would happily accept an `OrderId`
+* where a `CustomerId` is expected. `UuidIdentifier` solves both: the format
+* lives here once ({@link isValid}), and the `TBrand` phantom tag makes each
+* subtype nominally distinct so the ids cannot be swapped for one another.
+*
+* It deliberately does not impose a factory. Identifiers vary in how they
+* report an invalid value (their own exception type, their own message), so a
+* concrete id adds a validating `create` that calls {@link isValid} plus a
+* `reconstitute` that trusts an already-persisted value:
+*
+* ```ts
+* class OrderId extends UuidIdentifier<"OrderId"> {
+*   private constructor(value: string) { super(value); }
+*   static create(raw: string): OrderId {
+*     if (!UuidIdentifier.isValid(raw)) throw new InvalidOrderIdError(raw);
+*     return new OrderId(raw);
+*   }
+*   static reconstitute(value: string): OrderId { return new OrderId(value); }
+* }
+* ```
+*
+* @typeParam TBrand - A unique string literal that nominally tags the subtype.
+*/
+var UuidIdentifier = class extends ValueObject {
+	constructor(value) {
+		super(value);
+	}
+	toPrimitive() {
+		return this.value;
+	}
+	/** The wrapped UUID string — convenient for logging and interpolation. */
+	toString() {
+		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`.
+	*/
+	static isValid(candidate) {
+		return UUID_PATTERN.test(candidate);
+	}
+};
+//#endregion
+export { UuidIdentifier as t };
+
+//# sourceMappingURL=uuid-identifier.js.map

package/dist/uuid-identifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uuid-identifier.js","names":[],"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,cAEU,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"}