@cullet/erp-core 1.1.0 → 1.3.0

package/dist/validation-error.cjs

@@ -0,0 +1,1020 @@
+const require_unexpected_error = require("./unexpected-error.cjs");
+//#region src/core/errors/authentication-error.ts
+var AuthenticationError = class AuthenticationError extends require_unexpected_error.AppError {
+	constructor(params) {
+		super(params.message, params.code, {
+			cause: params.cause,
+			metadata: {
+				reason: params.reason,
+				...params.metadata ?? {}
+			},
+			type: params.type,
+			severity: params.severity,
+			correlationId: params.correlationId,
+			requestId: params.requestId,
+			commandId: params.commandId,
+			createdAtIso: params.createdAtIso,
+			publicMessage: params.publicMessage
+		});
+		this.reason = params.reason;
+		Object.freeze(this);
+	}
+	static missingToken(options) {
+		return new AuthenticationError({
+			message: "Missing credentials",
+			code: require_unexpected_error.ErrorCodes.authentication.missingToken,
+			reason: "missing_token",
+			metadata: compactMetadata$1(options),
+			...extractAppErrorOptions$1(options)
+		});
+	}
+	static invalidToken(options) {
+		return new AuthenticationError({
+			message: "Invalid credentials",
+			code: require_unexpected_error.ErrorCodes.authentication.invalidToken,
+			reason: "invalid_token",
+			metadata: compactMetadata$1({
+				authScheme: options?.authScheme,
+				tokenLocation: options?.tokenLocation,
+				details: options?.details,
+				correlationId: options?.correlationId,
+				requestId: options?.requestId
+			}),
+			...extractAppErrorOptions$1(options)
+		});
+	}
+	static expiredToken(options) {
+		return new AuthenticationError({
+			message: "Expired credentials",
+			code: require_unexpected_error.ErrorCodes.authentication.expiredToken,
+			reason: "expired_token",
+			metadata: compactMetadata$1(options),
+			...extractAppErrorOptions$1(options)
+		});
+	}
+	static invalidCredentials(options) {
+		return new AuthenticationError({
+			message: "Invalid username or password",
+			code: require_unexpected_error.ErrorCodes.authentication.invalidCredentials,
+			reason: "invalid_credentials",
+			metadata: compactMetadata$1(options),
+			...extractAppErrorOptions$1(options)
+		});
+	}
+};
+function extractAppErrorOptions$1(options) {
+	return {
+		cause: options?.cause,
+		type: options?.type,
+		severity: options?.severity,
+		correlationId: options?.correlationId,
+		requestId: options?.requestId,
+		commandId: options?.commandId,
+		createdAtIso: options?.createdAtIso,
+		publicMessage: options?.publicMessage
+	};
+}
+function compactMetadata$1(input) {
+	if (!input) return void 0;
+	return Object.fromEntries(Object.entries(input).filter(([, value]) => value !== void 0));
+}
+//#endregion
+//#region src/core/errors/authorization-error.ts
+/**
+* Raised when an authenticated actor is not allowed to perform a business
+* action — the "you may not" error, distinct from authentication ("who are
+* you"). Maps to an HTTP 403 at the edge.
+*
+* The discriminating {@link reason} records *why* access was denied (a flat
+* forbid, a missing role/capability, an out-of-scope target, or a policy
+* decision) so the boundary can shape the response without re-deriving it. The
+* metadata is deliberately built around a stable business `action` and a
+* type/id resource reference rather than an HTTP route or full payload, keeping
+* sensitive data out of logs. Instances are frozen. Construct through the
+* static factories, never directly.
+*/
+var AuthorizationError = class AuthorizationError extends require_unexpected_error.AppError {
+	constructor(params) {
+		super(params.message, params.code, {
+			cause: params.cause,
+			metadata: params.metadata,
+			type: params.type,
+			severity: params.severity,
+			correlationId: params.correlationId,
+			requestId: params.requestId,
+			commandId: params.commandId,
+			createdAtIso: params.createdAtIso,
+			publicMessage: params.publicMessage
+		});
+		this.reason = params.reason;
+		Object.freeze(this);
+	}
+	/**
+	* A flat denial with no more specific reason — the actor simply may not
+	* perform this action. Reach for a more precise factory
+	* ({@link AuthorizationError.missingCapability}, {@link AuthorizationError.outOfScope},
+	* {@link AuthorizationError.policyDenied}) when the cause is known.
+	*/
+	static forbidden(input) {
+		return new AuthorizationError({
+			message: "Action not allowed",
+			code: require_unexpected_error.ErrorCodes.authorization.forbidden,
+			reason: "forbidden",
+			metadata: {
+				reason: "forbidden",
+				...extractMetadataOnly(input)
+			},
+			...extractAppErrorOptions(input)
+		});
+	}
+	/**
+	* The action was denied by an evaluated policy. Captures the deciding
+	* policy's id, version, and evaluation instant into the metadata (with
+	* `decision: "deny"`) so the denial is auditable back to the exact policy
+	* that produced it.
+	*
+	* @param input - Factory options plus the required `policyId`,
+	*   `policyVersion`, and `evaluatedAtIso` of the deciding policy.
+	*/
+	static policyDenied(input) {
+		return new AuthorizationError({
+			message: "Action denied by policy",
+			code: require_unexpected_error.ErrorCodes.authorization.policyDenied,
+			reason: "policy_denied",
+			metadata: {
+				reason: "policy_denied",
+				...extractMetadataOnly(input),
+				decision: "deny"
+			},
+			...extractAppErrorOptions(input)
+		});
+	}
+	/**
+	* The actor lacks a required role or capability. The expected
+	* {@link AuthorizationRequirement} is recorded so the boundary can tell the
+	* caller precisely what grant is missing.
+	*
+	* @param input - Factory options plus the `required` role/capability/scope.
+	*/
+	static missingCapability(input) {
+		return new AuthorizationError({
+			message: "Insufficient capability to perform the action",
+			code: require_unexpected_error.ErrorCodes.authorization.missingCapability,
+			reason: "missing_capability",
+			metadata: {
+				reason: "missing_capability",
+				...extractMetadataOnly(input)
+			},
+			...extractAppErrorOptions(input)
+		});
+	}
+	/**
+	* The actor may perform the action in general, but not on *this* target —
+	* the resource falls outside the actor's permitted scope (e.g. a different
+	* school or tenant than the one they are bound to).
+	*
+	* @param input - Factory options plus the optional `required` scope that the
+	*   target failed to satisfy.
+	*/
+	static outOfScope(input) {
+		return new AuthorizationError({
+			message: "Action outside the allowed scope",
+			code: require_unexpected_error.ErrorCodes.authorization.outOfScope,
+			reason: "out_of_scope",
+			metadata: {
+				reason: "out_of_scope",
+				...extractMetadataOnly(input)
+			},
+			...extractAppErrorOptions(input)
+		});
+	}
+};
+function extractAppErrorOptions(options) {
+	return {
+		cause: options?.cause,
+		type: options?.type,
+		severity: options?.severity,
+		correlationId: options?.correlationId,
+		requestId: options?.requestId,
+		commandId: options?.commandId,
+		createdAtIso: options?.createdAtIso,
+		publicMessage: options?.publicMessage
+	};
+}
+function extractMetadataOnly(input) {
+	const { cause, type, severity, correlationId, requestId, commandId, createdAtIso, publicMessage, ...metadata } = input;
+	return metadata;
+}
+//#endregion
+//#region src/core/errors/conflict-error.ts
+/**
+* Base for errors that signal a state conflict — the request collides with data
+* that already exists. Common at an HTTP 409 boundary.
+*
+* The discriminating {@link kind} lets a handler branch on *why* it conflicted
+* (an already-existing record, a domain duplicate, or a raw storage uniqueness
+* breach) without `instanceof` chains. Abstract: construct one of the concrete
+* subclasses through its `detected(...)` factory, which fills in the right code,
+* message, and metadata. Instances are frozen, so a conflict error can be shared
+* and rethrown without risk of tampering.
+*/
+var ConflictError = class extends require_unexpected_error.AppError {
+	constructor(params) {
+		super(params.message, params.code, {
+			...params,
+			metadata: {
+				kind: params.kind,
+				...params.metadata
+			}
+		});
+		this.kind = params.kind;
+		Object.freeze(this);
+	}
+};
+/**
+* The operation cannot proceed because a matching record already exists —
+* e.g. creating something whose natural key is already taken. Construct via
+* {@link AlreadyExistsError.detected}.
+*/
+var AlreadyExistsError = class AlreadyExistsError extends ConflictError {
+	constructor(input) {
+		super({
+			message: "A matching record already exists for the requested operation",
+			code: require_unexpected_error.ErrorCodes.conflict.alreadyExists,
+			kind: "already_exists",
+			...input
+		});
+	}
+	/**
+	* Builds an {@link AlreadyExistsError} for a detected collision. `operation`
+	* defaults to `"create"` and a generic retry `hint` is supplied when none is
+	* given, so the error is actionable even from a minimal call site.
+	*
+	* @param input - The conflicting entity plus optional non-sensitive context
+	*   (operation, field, existing id, value hash/preview, correlation ids).
+	*/
+	static detected(input) {
+		return new AlreadyExistsError({
+			metadata: {
+				entity: input.entity,
+				operation: input.operation ?? "create",
+				field: input.field,
+				existingId: input.existingId,
+				valueHash: input.valueHash,
+				valuePreview: input.valuePreview,
+				detectedAtIso: input.detectedAtIso,
+				correlationId: input.correlationId,
+				requestId: input.requestId,
+				commandId: input.commandId,
+				hint: input.hint ?? "Verify existing records before retrying."
+			},
+			cause: input.cause
+		});
+	}
+};
+/**
+* A domain-level duplicate: the data being written would duplicate an existing
+* record under the model's own uniqueness rules. Use this when the duplication
+* is recognized in the domain, as opposed to a raw DB constraint
+* ({@link UniqueConstraintViolationError}). Construct via
+* {@link DuplicateError.detected}.
+*/
+var DuplicateError = class DuplicateError extends ConflictError {
+	constructor(input) {
+		super({
+			message: "Conflict: an existing record violates uniqueness",
+			code: require_unexpected_error.ErrorCodes.conflict.duplicate,
+			kind: "duplicate",
+			...input
+		});
+	}
+	/**
+	* Builds a {@link DuplicateError} for a detected duplicate, defaulting to a
+	* "adjust the data so it does not duplicate" hint when none is provided.
+	*
+	* @param input - The conflicting entity plus optional non-sensitive context
+	*   (field, constraint name, existing id, value hash/preview, correlation ids).
+	*/
+	static detected(input) {
+		return new DuplicateError({
+			metadata: {
+				entity: input.entity,
+				operation: input.operation,
+				field: input.field,
+				constraintName: input.constraintName,
+				existingId: input.existingId,
+				valueHash: input.valueHash,
+				valuePreview: input.valuePreview,
+				detectedAtIso: input.detectedAtIso,
+				correlationId: input.correlationId,
+				requestId: input.requestId,
+				commandId: input.commandId,
+				hint: input.hint ?? "Adjust the data so it does not duplicate existing records."
+			},
+			cause: input.cause
+		});
+	}
+};
+/**
+* A uniqueness breach surfaced by the storage layer itself (a database unique
+* index), carrying the raw {@link UniqueConstraintViolation} (constraint, table,
+* columns). Keep this distinct from {@link DuplicateError}: this one is the
+* infrastructure signal; translate it into a domain duplicate at the boundary
+* with {@link translateUniqueViolationToDuplicate} when the model should own the
+* message. Construct via {@link UniqueConstraintViolationError.detected}.
+*/
+var UniqueConstraintViolationError = class UniqueConstraintViolationError extends ConflictError {
+	constructor(input) {
+		super({
+			message: "Uniqueness violation in storage",
+			code: require_unexpected_error.ErrorCodes.conflict.uniqueViolation,
+			kind: "unique_violation",
+			...input
+		});
+	}
+	/**
+	* Builds a {@link UniqueConstraintViolationError} from the constraint details
+	* a driver reports, packaging them into a nested `violation` payload.
+	*
+	* @param input - The entity plus the offending constraint name, table, and
+	*   columns, and optional correlation ids.
+	*/
+	static detected(input) {
+		return new UniqueConstraintViolationError({
+			metadata: {
+				entity: input.entity,
+				operation: input.operation,
+				constraintName: input.constraintName,
+				detectedAtIso: input.detectedAtIso,
+				correlationId: input.correlationId,
+				requestId: input.requestId,
+				commandId: input.commandId,
+				violation: {
+					kind: "unique_violation",
+					constraintName: input.constraintName,
+					table: input.table,
+					columns: input.columns
+				},
+				hint: "Uniqueness conflict detected in the database."
+			},
+			cause: input.cause
+		});
+	}
+};
+/**
+* Translates a raw storage {@link UniqueConstraintViolation} into a domain-level
+* {@link DuplicateError}. This is the seam where an infrastructure concern (a DB
+* unique index firing) is re-expressed in the language of the model, so callers
+* upstream catch a `DuplicateError` and never have to know a database was
+* involved.
+*
+* @param input - The entity, the driver-reported `violation`, and optional
+*   request context (`ctx`) carrying correlation ids and a clock instant.
+* @returns A {@link DuplicateError} carrying the constraint name as its field hint.
+*/
+function translateUniqueViolationToDuplicate(input) {
+	return DuplicateError.detected({
+		entity: input.entity,
+		operation: input.operation,
+		field: input.field,
+		constraintName: input.violation.constraintName,
+		detectedAtIso: input.ctx?.nowIso,
+		correlationId: input.ctx?.correlationId,
+		requestId: input.ctx?.requestId,
+		commandId: input.ctx?.commandId,
+		cause: input.cause
+	});
+}
+//#endregion
+//#region src/core/errors/idempotency-error.ts
+var IdempotencyError = class extends require_unexpected_error.AppError {
+	constructor(input) {
+		super(input.message, input.code, {
+			cause: input.cause,
+			metadata: {
+				kind: input.kind,
+				...input.metadata
+			}
+		});
+		this.kind = input.kind;
+		Object.freeze(this);
+	}
+	static keyMissing(input) {
+		return IdempotencyKeyMissingError.detected(input);
+	}
+	static inProgress(input) {
+		return IdempotencyInProgressError.detected(input);
+	}
+	static payloadMismatch(input) {
+		return IdempotencyPayloadMismatchError.detected(input);
+	}
+	static replayNotSupported(input) {
+		return IdempotencyReplayNotSupportedError.detected(input);
+	}
+};
+var IdempotencyKeyMissingError = class IdempotencyKeyMissingError extends IdempotencyError {
+	constructor(input) {
+		super({
+			message: "Idempotency key/commandId missing for the requested operation",
+			code: require_unexpected_error.ErrorCodes.idempotency.keyMissing,
+			kind: "key_missing",
+			metadata: input.metadata,
+			cause: input.cause
+		});
+	}
+	static detected(input) {
+		return new IdempotencyKeyMissingError({
+			cause: input.cause,
+			metadata: {
+				operation: input.operation,
+				scope: input.scope,
+				entity: input.entity,
+				correlationId: input.correlationId,
+				requestId: input.requestId,
+				commandId: input.commandId,
+				detectedAtIso: input.detectedAtIso,
+				hint: input.hint ?? "Send a commandId/idempotency key to prevent duplicate processing.",
+				details: input.details
+			}
+		});
+	}
+};
+var IdempotencyInProgressError = class IdempotencyInProgressError extends IdempotencyError {
+	constructor(input) {
+		super({
+			message: "The same business intent is already being processed",
+			code: require_unexpected_error.ErrorCodes.idempotency.inProgress,
+			kind: "in_progress",
+			metadata: input.metadata,
+			cause: input.cause
+		});
+	}
+	static detected(input) {
+		const resolved = resolveKeyIdentity(input.key, input.keyHash, input.keyPreview);
+		return new IdempotencyInProgressError({
+			cause: input.cause,
+			metadata: {
+				operation: input.operation,
+				scope: input.scope,
+				entity: input.entity,
+				keyHash: resolved.keyHash,
+				keyPreview: resolved.keyPreview,
+				idempotencyRecordId: input.idempotencyRecordId,
+				correlationId: input.correlationId,
+				requestId: input.requestId,
+				commandId: input.commandId,
+				detectedAtIso: input.detectedAtIso,
+				hint: input.hint ?? "Wait for completion and retry using the same key.",
+				details: input.details
+			}
+		});
+	}
+};
+var IdempotencyPayloadMismatchError = class IdempotencyPayloadMismatchError extends IdempotencyError {
+	constructor(input) {
+		super({
+			message: "The idempotency key was reused with a different payload",
+			code: require_unexpected_error.ErrorCodes.idempotency.payloadMismatch,
+			kind: "payload_mismatch",
+			metadata: input.metadata,
+			cause: input.cause
+		});
+	}
+	static detected(input) {
+		const resolved = resolveKeyIdentity(input.key, input.keyHash, input.keyPreview);
+		return new IdempotencyPayloadMismatchError({
+			cause: input.cause,
+			metadata: {
+				operation: input.operation,
+				scope: input.scope,
+				entity: input.entity,
+				keyHash: resolved.keyHash,
+				keyPreview: resolved.keyPreview,
+				incomingPayloadHash: input.incomingPayloadHash,
+				existingPayloadHash: input.existingPayloadHash,
+				idempotencyRecordId: input.idempotencyRecordId,
+				correlationId: input.correlationId,
+				requestId: input.requestId,
+				commandId: input.commandId,
+				detectedAtIso: input.detectedAtIso,
+				hint: input.hint ?? "Use a new idempotency key for a new intent. The same key should only be reused for retries of the same payload.",
+				details: input.details
+			}
+		});
+	}
+};
+var IdempotencyReplayNotSupportedError = class IdempotencyReplayNotSupportedError extends IdempotencyError {
+	constructor(input) {
+		super({
+			message: "Re-execution detected, but replay of the previous result is not implemented",
+			code: require_unexpected_error.ErrorCodes.idempotency.replayNotSupported,
+			kind: "replay_not_supported",
+			metadata: input.metadata,
+			cause: input.cause
+		});
+	}
+	static detected(input) {
+		const resolved = resolveKeyIdentity(input.key, input.keyHash, input.keyPreview);
+		return new IdempotencyReplayNotSupportedError({
+			cause: input.cause,
+			metadata: {
+				operation: input.operation,
+				scope: input.scope,
+				entity: input.entity,
+				keyHash: resolved.keyHash,
+				keyPreview: resolved.keyPreview,
+				idempotencyRecordId: input.idempotencyRecordId,
+				correlationId: input.correlationId,
+				requestId: input.requestId,
+				commandId: input.commandId,
+				detectedAtIso: input.detectedAtIso,
+				hint: input.hint ?? "Try again later, or enable result replay for full idempotency.",
+				details: input.details
+			}
+		});
+	}
+};
+function resolveKeyIdentity(key, keyHash, keyPreview) {
+	return {
+		keyHash,
+		keyPreview: keyPreview ?? (key ? key.length <= 8 ? key : key.slice(0, 8) : void 0)
+	};
+}
+//#endregion
+//#region src/core/errors/integration-error.ts
+/**
+* Raised when a call to an external provider fails — a timeout, an unreachable
+* endpoint, or a malformed response. This is the boundary error that separates
+* "our code is fine, the outside world misbehaved" from internal faults, which
+* matters for retry and alerting decisions.
+*
+* Every instance records the `provider`, the `operation`, and timing
+* (`startedAtIso` / `durationMs`) so failures are correlatable across services
+* and a slow dependency is visible in the metadata. The discriminating
+* {@link reason} lets callers decide whether a failure is worth retrying.
+* Instances are frozen; construct through the static factories.
+*/
+var IntegrationError = class IntegrationError extends require_unexpected_error.AppError {
+	constructor(params) {
+		const { message, code, metadata, ...rest } = params;
+		super(message, code, {
+			...rest,
+			metadata
+		});
+		this.reason = params.reason;
+		Object.freeze(this);
+	}
+	/**
+	* The provider did not respond within the allotted time. Usually retryable,
+	* since a timeout leaves the outcome unknown rather than known-failed.
+	*/
+	static timeout(options) {
+		return new IntegrationError({
+			message: "Timeout while integrating with external provider",
+			code: require_unexpected_error.ErrorCodes.integration.timeout,
+			reason: "timeout",
+			metadata: buildMetadata({
+				reason: "timeout",
+				...options
+			}),
+			...pickAppErrorFields(options)
+		});
+	}
+	/**
+	* The provider could not be reached at all (connection refused, DNS
+	* failure, network partition) — the request never landed.
+	*/
+	static unreachable(options) {
+		return new IntegrationError({
+			message: "Provider unavailable",
+			code: require_unexpected_error.ErrorCodes.integration.unreachable,
+			reason: "unreachable",
+			metadata: buildMetadata({
+				reason: "unreachable",
+				...options
+			}),
+			...pickAppErrorFields(options)
+		});
+	}
+	/**
+	* The provider answered, but with something the system cannot use — an
+	* unexpected status, an unparsable body, or a contract mismatch. Unlike a
+	* timeout this is a definite failure, so blind retries rarely help.
+	*/
+	static badResponse(options) {
+		return new IntegrationError({
+			message: "Unexpected response from provider",
+			code: require_unexpected_error.ErrorCodes.integration.badResponse,
+			reason: "bad_response",
+			metadata: buildMetadata({
+				reason: "bad_response",
+				...options
+			}),
+			...pickAppErrorFields(options)
+		});
+	}
+};
+function buildMetadata(input) {
+	return compactMetadata({
+		reason: input.reason,
+		provider: input.provider,
+		operation: input.operation,
+		startedAtIso: input.startedAtIso,
+		durationMs: input.durationMs,
+		detectedAtIso: input.detectedAtIso,
+		correlationId: input.correlationId,
+		requestId: input.requestId,
+		commandId: input.commandId,
+		details: input.details,
+		statusCode: input.statusCode,
+		responseCode: input.responseCode
+	});
+}
+function pickAppErrorFields(options) {
+	return {
+		cause: options.cause,
+		type: options.type,
+		severity: options.severity,
+		correlationId: options.correlationId,
+		requestId: options.requestId,
+		commandId: options.commandId,
+		createdAtIso: options.createdAtIso,
+		publicMessage: options.publicMessage
+	};
+}
+function compactMetadata(input) {
+	return Object.fromEntries(Object.entries(input).filter(([, value]) => value !== void 0));
+}
+//#endregion
+//#region src/core/errors/legacy-incompatible-error.ts
+var LegacyIncompatibleError = class extends require_unexpected_error.AppError {
+	constructor(message, context, options) {
+		const mergedMetadata = options?.metadata ? {
+			...context ?? {},
+			...options.metadata
+		} : context;
+		super(message, require_unexpected_error.ErrorCodes.legacyIncompatible, {
+			...options,
+			metadata: mergedMetadata
+		});
+	}
+};
+//#endregion
+//#region src/core/errors/serialization-error.ts
+var SerializationError = class extends require_unexpected_error.AppError {
+	constructor(input) {
+		super(input.message ?? "Serialization failure", input.code, {
+			cause: input.cause,
+			metadata: {
+				direction: input.direction,
+				category: input.category,
+				...input.metadata
+			},
+			type: input.type,
+			severity: input.severity,
+			correlationId: input.correlationId,
+			requestId: input.requestId,
+			commandId: input.commandId,
+			createdAtIso: input.createdAtIso,
+			publicMessage: input.publicMessage
+		});
+		this.direction = input.direction;
+		this.category = input.category;
+		this.boundary = input.metadata.boundary;
+		this.contract = input.metadata.contract;
+		Object.freeze(this);
+	}
+};
+var SerializationInError = class SerializationInError extends SerializationError {
+	constructor(input) {
+		super(input);
+	}
+	static failure(category, metadata) {
+		return new SerializationInError({
+			message: SerializationMessages.message("deserialize", category),
+			code: SerializationCodes.code("deserialize", category),
+			category,
+			direction: "deserialize",
+			metadata,
+			cause: metadata.cause
+		});
+	}
+};
+var SerializationOutError = class SerializationOutError extends SerializationError {
+	constructor(input) {
+		super(input);
+	}
+	static failure(category, metadata) {
+		return new SerializationOutError({
+			message: SerializationMessages.message("serialize", category),
+			code: SerializationCodes.code("serialize", category),
+			category,
+			direction: "serialize",
+			metadata,
+			cause: metadata.cause
+		});
+	}
+};
+var SerializationCodes = class {
+	static code(direction, category) {
+		return require_unexpected_error.serializationErrorCode(direction, category);
+	}
+};
+var SerializationMessages = class {
+	static message(direction, category) {
+		if (direction === "deserialize") {
+			if (category === "invalid_json") return "Invalid payload: malformed JSON";
+			if (category === "schema_version_missing") return "Invalid payload: schemaVersion is missing";
+			if (category === "schema_version_unsupported") return "Invalid payload: schemaVersion is not supported";
+			if (category === "invalid_shape") return "Invalid payload: incompatible shape";
+			if (category === "mapping_not_implemented") return "Unsupported payload: mapping not implemented";
+			if (category === "contract_mismatch") return "Payload does not match the expected contract";
+			return "Failed to parse incoming payload";
+		}
+		if (category === "stringify_failed") return "Failed to serialize the response";
+		if (category === "contract_mismatch") return "Response does not match the expected contract";
+		return "Failed to build the response";
+	}
+};
+function safePreview(value, limit = 240) {
+	try {
+		const serialized = typeof value === "string" ? value : JSON.stringify(value);
+		return serialized.length > limit ? `${serialized.slice(0, limit)}…` : serialized;
+	} catch {
+		return;
+	}
+}
+//#endregion
+//#region src/core/errors/temporal-error.ts
+var TemporalError = class extends require_unexpected_error.AppError {
+	constructor(input) {
+		super(input.message, input.code, {
+			...input,
+			metadata: {
+				kind: input.kind,
+				...input.metadata
+			}
+		});
+		this.kind = input.kind;
+		this.resourceType = input.metadata.resourceType;
+		this.evaluatedAtIso = input.metadata.evaluatedAtIso;
+		Object.freeze(this);
+	}
+};
+var ExpiredError = class ExpiredError extends TemporalError {
+	constructor(input) {
+		super(input);
+	}
+	static detected(input) {
+		return new ExpiredError({
+			message: "The validity of the resource/action has expired",
+			code: require_unexpected_error.ErrorCodes.temporal.expired,
+			kind: "expired",
+			metadata: {
+				...input,
+				hint: input.hint ?? "The window has expired. Request a new link or try again within the valid period."
+			},
+			cause: input.cause,
+			type: input.type,
+			severity: input.severity,
+			correlationId: input.correlationId,
+			requestId: input.requestId,
+			commandId: input.commandId,
+			createdAtIso: input.createdAtIso,
+			publicMessage: input.publicMessage
+		});
+	}
+};
+var NotYetValidError = class NotYetValidError extends TemporalError {
+	constructor(input) {
+		super(input);
+	}
+	static detected(input) {
+		return new NotYetValidError({
+			message: "The resource/action is not yet valid",
+			code: require_unexpected_error.ErrorCodes.temporal.notYetValid,
+			kind: "not_yet_valid",
+			metadata: {
+				...input,
+				hint: input.hint ?? "Not yet within the valid period. Try again later."
+			},
+			cause: input.cause,
+			type: input.type,
+			severity: input.severity,
+			correlationId: input.correlationId,
+			requestId: input.requestId,
+			commandId: input.commandId,
+			createdAtIso: input.createdAtIso,
+			publicMessage: input.publicMessage
+		});
+	}
+};
+function evaluateTemporalWindow(input) {
+	const evaluatedMs = Date.parse(input.evaluatedAtIso);
+	if (Number.isNaN(evaluatedMs)) return null;
+	let notYetValid = false;
+	if (input.validFromIso) {
+		const fromMs = Date.parse(input.validFromIso);
+		if (!Number.isNaN(fromMs) && evaluatedMs < fromMs) notYetValid = true;
+	}
+	if (input.validUntilIso) {
+		const untilMs = Date.parse(input.validUntilIso);
+		if (!Number.isNaN(untilMs) && evaluatedMs > untilMs) return {
+			expired: true,
+			notYetValid: false
+		};
+	}
+	return {
+		expired: false,
+		notYetValid
+	};
+}
+//#endregion
+//#region src/core/errors/validation-error.ts
+/**
+* Raised when a single input fails a validation rule — the canonical
+* "this field is wrong, and here is why" error.
+*
+* It pins the offending `field` and a machine-readable `validationCode` into
+* the metadata (merged ahead of any caller-supplied metadata) so an API layer
+* can map the failure straight onto a form field without parsing the message.
+* The fixed {@link ErrorCodes.validation} code lets callers catch all
+* validation failures uniformly while still distinguishing the specific rule
+* through `validationCode`.
+*/
+var ValidationError = class extends require_unexpected_error.AppError {
+	/**
+	* @param field - The input that failed validation; surfaced as `metadata.field`.
+	* @param code - The specific rule that was violated; surfaced as `metadata.validationCode`.
+	* @param message - The developer-facing description of the failure.
+	* @param options - Optional cause, correlation ids, and extra metadata
+	*   (merged over the field/code metadata, never overwriting it by accident).
+	*/
+	constructor(field, code, message, options) {
+		const baseMetadata = {
+			field: field.value,
+			validationCode: code.value
+		};
+		const mergedMetadata = options?.metadata ? {
+			...baseMetadata,
+			...options.metadata
+		} : baseMetadata;
+		super(message, require_unexpected_error.ErrorCodes.validation, {
+			...options,
+			metadata: mergedMetadata
+		});
+	}
+};
+//#endregion
+Object.defineProperty(exports, "AlreadyExistsError", {
+	enumerable: true,
+	get: function() {
+		return AlreadyExistsError;
+	}
+});
+Object.defineProperty(exports, "AuthenticationError", {
+	enumerable: true,
+	get: function() {
+		return AuthenticationError;
+	}
+});
+Object.defineProperty(exports, "AuthorizationError", {
+	enumerable: true,
+	get: function() {
+		return AuthorizationError;
+	}
+});
+Object.defineProperty(exports, "ConflictError", {
+	enumerable: true,
+	get: function() {
+		return ConflictError;
+	}
+});
+Object.defineProperty(exports, "DuplicateError", {
+	enumerable: true,
+	get: function() {
+		return DuplicateError;
+	}
+});
+Object.defineProperty(exports, "ExpiredError", {
+	enumerable: true,
+	get: function() {
+		return ExpiredError;
+	}
+});
+Object.defineProperty(exports, "IdempotencyError", {
+	enumerable: true,
+	get: function() {
+		return IdempotencyError;
+	}
+});
+Object.defineProperty(exports, "IdempotencyInProgressError", {
+	enumerable: true,
+	get: function() {
+		return IdempotencyInProgressError;
+	}
+});
+Object.defineProperty(exports, "IdempotencyKeyMissingError", {
+	enumerable: true,
+	get: function() {
+		return IdempotencyKeyMissingError;
+	}
+});
+Object.defineProperty(exports, "IdempotencyPayloadMismatchError", {
+	enumerable: true,
+	get: function() {
+		return IdempotencyPayloadMismatchError;
+	}
+});
+Object.defineProperty(exports, "IdempotencyReplayNotSupportedError", {
+	enumerable: true,
+	get: function() {
+		return IdempotencyReplayNotSupportedError;
+	}
+});
+Object.defineProperty(exports, "IntegrationError", {
+	enumerable: true,
+	get: function() {
+		return IntegrationError;
+	}
+});
+Object.defineProperty(exports, "LegacyIncompatibleError", {
+	enumerable: true,
+	get: function() {
+		return LegacyIncompatibleError;
+	}
+});
+Object.defineProperty(exports, "NotYetValidError", {
+	enumerable: true,
+	get: function() {
+		return NotYetValidError;
+	}
+});
+Object.defineProperty(exports, "SerializationCodes", {
+	enumerable: true,
+	get: function() {
+		return SerializationCodes;
+	}
+});
+Object.defineProperty(exports, "SerializationError", {
+	enumerable: true,
+	get: function() {
+		return SerializationError;
+	}
+});
+Object.defineProperty(exports, "SerializationInError", {
+	enumerable: true,
+	get: function() {
+		return SerializationInError;
+	}
+});
+Object.defineProperty(exports, "SerializationMessages", {
+	enumerable: true,
+	get: function() {
+		return SerializationMessages;
+	}
+});
+Object.defineProperty(exports, "SerializationOutError", {
+	enumerable: true,
+	get: function() {
+		return SerializationOutError;
+	}
+});
+Object.defineProperty(exports, "TemporalError", {
+	enumerable: true,
+	get: function() {
+		return TemporalError;
+	}
+});
+Object.defineProperty(exports, "UniqueConstraintViolationError", {
+	enumerable: true,
+	get: function() {
+		return UniqueConstraintViolationError;
+	}
+});
+Object.defineProperty(exports, "ValidationError", {
+	enumerable: true,
+	get: function() {
+		return ValidationError;
+	}
+});
+Object.defineProperty(exports, "evaluateTemporalWindow", {
+	enumerable: true,
+	get: function() {
+		return evaluateTemporalWindow;
+	}
+});
+Object.defineProperty(exports, "safePreview", {
+	enumerable: true,
+	get: function() {
+		return safePreview;
+	}
+});
+Object.defineProperty(exports, "translateUniqueViolationToDuplicate", {
+	enumerable: true,
+	get: function() {
+		return translateUniqueViolationToDuplicate;
+	}
+});
+
+//# sourceMappingURL=validation-error.cjs.map