@cullet/erp-core 1.1.0 → 1.3.0

package/dist/validation-error.d.cts

@@ -0,0 +1,777 @@
+import { a as JsonSafeRecord, n as AppErrorOptions, r as ErrorSeverity, t as AppError } from "./app-error.cjs";
+import { t as ValidationCode } from "./validation-code.cjs";
+import { t as ValidationField } from "./validation-field.cjs";
+
+//#region src/core/errors/error-codes.d.ts
+declare const ErrorCodes: {
+  readonly authentication: {
+    readonly missingToken: "sec.authn.missing_token";
+    readonly invalidToken: "sec.authn.invalid_token";
+    readonly expiredToken: "sec.authn.expired_token";
+    readonly invalidCredentials: "sec.authn.invalid_credentials";
+  };
+  readonly authorization: {
+    readonly forbidden: "sec.authz.forbidden";
+    readonly policyDenied: "sec.authz.policy_denied";
+    readonly missingCapability: "sec.authz.missing_capability";
+    readonly outOfScope: "sec.authz.out_of_scope";
+  };
+  readonly businessRuleViolation: "business_rule_violation";
+  readonly conflict: {
+    readonly alreadyExists: "conf.already_exists";
+    readonly duplicate: "conf.duplicate";
+    readonly uniqueViolation: "conf.unique_violation";
+  };
+  readonly idempotency: {
+    readonly keyMissing: "idemp.key_missing";
+    readonly inProgress: "idemp.in_progress";
+    readonly payloadMismatch: "idemp.payload_mismatch";
+    readonly replayNotSupported: "idemp.replay_not_supported";
+  };
+  readonly integration: {
+    readonly timeout: "int.timeout";
+    readonly unreachable: "int.unreachable";
+    readonly badResponse: "int.bad_response";
+  };
+  readonly legacyIncompatible: "legacy_incompatible";
+  readonly notFound: "not_found";
+  readonly serialization: {
+    readonly deserializePrefix: "ser.des";
+    readonly serializePrefix: "ser.ser";
+  };
+  readonly temporal: {
+    readonly expired: "tmp.expired";
+    readonly notYetValid: "tmp.not_yet_valid";
+  };
+  readonly unexpected: "unexpected";
+  readonly validation: "validation_error";
+};
+type SerializationCodeDirection = "deserialize" | "serialize";
+declare function serializationErrorCode(direction: SerializationCodeDirection, category: string): string;
+//#endregion
+//#region src/core/errors/utils/json-safe.d.ts
+/**
+ * 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.
+ */
+declare function assertJsonSafeMetadata(input: unknown): JsonSafeRecord;
+//#endregion
+//#region src/core/errors/authentication-error.d.ts
+type AuthenticationErrorReason = "missing_token" | "malformed_token" | "invalid_token" | "expired_token" | "revoked_token" | "invalid_credentials" | "session_not_found" | "session_expired" | "unknown";
+type AuthenticationErrorMetadata = {
+  reason: AuthenticationErrorReason;
+  authScheme?: "bearer" | "cookie" | "basic" | "unknown";
+  tokenLocation?: "header" | "cookie" | "query" | "unknown";
+  expiresAtIso?: string;
+  correlationId?: string;
+  requestId?: string;
+  details?: string;
+};
+type AuthenticationErrorFactoryOptions = Omit<AuthenticationErrorMetadata, "reason"> & Omit<AppErrorOptions, "metadata">;
+declare class AuthenticationError extends AppError {
+  readonly reason: AuthenticationErrorReason;
+  private constructor();
+  static missingToken(options?: AuthenticationErrorFactoryOptions): AuthenticationError;
+  static invalidToken(options?: AuthenticationErrorFactoryOptions & {
+    cause?: unknown;
+  }): AuthenticationError;
+  static expiredToken(options?: AuthenticationErrorFactoryOptions & {
+    sessionId?: string;
+  }): AuthenticationError;
+  static invalidCredentials(options?: Pick<AuthenticationErrorFactoryOptions, "correlationId" | "requestId" | "type" | "severity" | "createdAtIso" | "publicMessage">): AuthenticationError;
+}
+//#endregion
+//#region src/core/errors/authorization-error.d.ts
+type AuthorizationErrorReason = "forbidden" | "missing_role" | "missing_capability" | "out_of_scope" | "outside_time_window" | "policy_denied" | "unknown";
+type AuthorizationRequirement = {
+  role?: string;
+  capability?: string;
+  scope?: string;
+};
+type AuthorizationErrorMetadata = {
+  reason: AuthorizationErrorReason;
+  /** Stable action you evaluated (not an HTTP route — a "business action") */
+  action: string;
+  /** Resource identification (without leaking the full payload) */
+  resource?: {
+    type: string;
+    id?: string;
+  };
+  /** Optional: actor (do not include sensitive data) */
+  actor?: {
+    userId: string;
+    role?: string;
+  };
+  /** Optional: expected requirement */
+  required?: AuthorizationRequirement;
+  /** Optional: policy (when you already have PolicyEvaluation or similar) */
+  policyId?: string;
+  policyVersion?: number;
+  evaluatedAtIso?: string;
+  decision?: "allow" | "deny";
+  reasonCode?: string;
+  /** Optional: additional non-sensitive info */
+  details?: string;
+};
+/**
+ * Options for AuthorizationError factory methods.
+ * Combines metadata fields (except 'reason') with common AppError options.
+ */
+type AuthorizationErrorFactoryOptions = Omit<AuthorizationErrorMetadata, "reason"> & Omit<AppErrorOptions, "metadata">;
+/**
+ * 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.
+ */
+declare class AuthorizationError extends AppError {
+  readonly reason: AuthorizationErrorReason;
+  private constructor();
+  /**
+   * 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: AuthorizationErrorFactoryOptions): AuthorizationError;
+  /**
+   * 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: AuthorizationErrorFactoryOptions & {
+    policyId: string;
+    policyVersion: number;
+    evaluatedAtIso: string;
+  }): AuthorizationError;
+  /**
+   * 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: AuthorizationErrorFactoryOptions & {
+    required: AuthorizationRequirement;
+  }): AuthorizationError;
+  /**
+   * 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: AuthorizationErrorFactoryOptions & {
+    required?: AuthorizationRequirement;
+  }): AuthorizationError;
+}
+//#endregion
+//#region src/core/errors/business-rule-violation-error.d.ts
+declare class BusinessRuleViolationError extends AppError {
+  constructor(rule: string, message: string, detail?: Record<string, unknown>, options?: AppErrorOptions);
+}
+//#endregion
+//#region src/core/errors/conflict-error.d.ts
+/**
+ * Conflict kinds we want to distinguish semantically.
+ */
+type ConflictKind = "already_exists" | "duplicate" | "unique_violation";
+/**
+ * Metadata attached to conflicts without exposing sensitive values.
+ */
+type ConflictErrorMetadata = {
+  kind: ConflictKind;
+  entity: string;
+  operation?: string;
+  field?: string;
+  constraintName?: string;
+  existingId?: string;
+  valueHash?: string;
+  valuePreview?: string;
+  detectedAtIso?: string;
+  correlationId?: string;
+  requestId?: string;
+  commandId?: string;
+  hint?: string;
+};
+/**
+ * Storage-level description of a unique-constraint breach, as reported by a
+ * database driver. Used to translate a raw DB error into a domain
+ * {@link DuplicateError} via {@link translateUniqueViolationToDuplicate}.
+ */
+type UniqueConstraintViolation = {
+  kind: "unique_violation";
+  constraintName?: string;
+  table?: string;
+  columns?: string[];
+};
+/**
+ * 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.
+ */
+declare abstract class ConflictError extends AppError {
+  readonly kind: ConflictKind;
+  protected constructor(params: {
+    message: string;
+    code: string;
+    kind: ConflictKind;
+    metadata: Omit<ConflictErrorMetadata, "kind">;
+    cause?: unknown;
+  } & AppErrorOptions);
+}
+/**
+ * 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}.
+ */
+declare class AlreadyExistsError extends ConflictError {
+  private constructor();
+  /**
+   * 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: {
+    entity: string;
+    operation?: string;
+    field?: string;
+    existingId?: string;
+    valueHash?: string;
+    valuePreview?: string;
+    detectedAtIso?: string;
+    correlationId?: string;
+    requestId?: string;
+    commandId?: string;
+    hint?: string;
+    cause?: unknown;
+  }): AlreadyExistsError;
+}
+/**
+ * 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}.
+ */
+declare class DuplicateError extends ConflictError {
+  private constructor();
+  /**
+   * 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: {
+    entity: string;
+    operation?: string;
+    field?: string;
+    constraintName?: string;
+    existingId?: string;
+    valueHash?: string;
+    valuePreview?: string;
+    detectedAtIso?: string;
+    correlationId?: string;
+    requestId?: string;
+    commandId?: string;
+    hint?: string;
+    cause?: unknown;
+  }): DuplicateError;
+}
+/**
+ * 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}.
+ */
+declare class UniqueConstraintViolationError extends ConflictError {
+  private constructor();
+  /**
+   * 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: {
+    entity: string;
+    operation?: string;
+    constraintName?: string;
+    table?: string;
+    columns?: string[];
+    detectedAtIso?: string;
+    correlationId?: string;
+    requestId?: string;
+    commandId?: string;
+    cause?: unknown;
+  }): UniqueConstraintViolationError;
+}
+/**
+ * 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.
+ */
+declare function translateUniqueViolationToDuplicate(input: {
+  entity: string;
+  operation?: string;
+  violation: UniqueConstraintViolation;
+  field?: string;
+  ctx?: {
+    correlationId?: string;
+    requestId?: string;
+    commandId?: string;
+    nowIso?: string;
+  };
+  cause?: unknown;
+}): DuplicateError;
+//#endregion
+//#region src/core/shared/hashing.d.ts
+declare function sha256Hex(value: string): string;
+/**
+ * Deterministic JSON string with object keys sorted recursively, so key order
+ * does not affect the output.
+ *
+ * Follows `JSON.stringify` semantics for the values it serializes: `undefined`,
+ * functions and symbols are dropped, non-finite numbers become `null`, `bigint`
+ * throws, and `Map`/`Set` serialize as `{}`. Distinct payloads can therefore
+ * collapse to the same string — for collision-resistant hashing use
+ * `PolicyHashing.canonicalJson` (policies/utils), which rejects those values
+ * up front.
+ *
+ * @throws {TypeError} On circular references (mirroring `JSON.stringify`).
+ */
+declare function stableStringify(value: unknown): string;
+declare function payloadHash(value: unknown): string;
+//#endregion
+//#region src/core/errors/idempotency-error.d.ts
+type IdempotencyFailureKind = "key_missing" | "in_progress" | "payload_mismatch" | "replay_not_supported" | "unknown";
+type IdempotencyErrorMetadata = {
+  kind: IdempotencyFailureKind;
+  operation: string;
+  scope?: string;
+  entity?: string;
+  keyHash?: string;
+  keyPreview?: string;
+  incomingPayloadHash?: string;
+  existingPayloadHash?: string;
+  idempotencyRecordId?: string;
+  correlationId?: string;
+  requestId?: string;
+  commandId?: string;
+  detectedAtIso?: string;
+  hint?: string;
+  details?: string;
+};
+type IdempotencyErrorConstructorInput = {
+  message: string;
+  code: string;
+  kind: IdempotencyFailureKind;
+  metadata: Omit<IdempotencyErrorMetadata, "kind">;
+  cause?: unknown;
+};
+declare abstract class IdempotencyError extends AppError {
+  readonly kind: IdempotencyFailureKind;
+  protected constructor(input: IdempotencyErrorConstructorInput);
+  static keyMissing(input: {
+    operation: string;
+    scope?: string;
+    entity?: string;
+    correlationId?: string;
+    requestId?: string;
+    commandId?: string;
+    detectedAtIso?: string;
+    hint?: string;
+    details?: string;
+    cause?: unknown;
+  }): IdempotencyKeyMissingError;
+  static inProgress(input: {
+    operation: string;
+    scope?: string;
+    entity?: string;
+    key?: string;
+    keyHash?: string;
+    keyPreview?: string;
+    idempotencyRecordId?: string;
+    correlationId?: string;
+    requestId?: string;
+    commandId?: string;
+    detectedAtIso?: string;
+    hint?: string;
+    details?: string;
+    cause?: unknown;
+  }): IdempotencyInProgressError;
+  static payloadMismatch(input: {
+    operation: string;
+    scope?: string;
+    entity?: string;
+    key?: string;
+    keyHash?: string;
+    keyPreview?: string;
+    incomingPayloadHash?: string;
+    existingPayloadHash?: string;
+    idempotencyRecordId?: string;
+    correlationId?: string;
+    requestId?: string;
+    commandId?: string;
+    detectedAtIso?: string;
+    hint?: string;
+    details?: string;
+    cause?: unknown;
+  }): IdempotencyPayloadMismatchError;
+  static replayNotSupported(input: {
+    operation: string;
+    scope?: string;
+    entity?: string;
+    key?: string;
+    keyHash?: string;
+    keyPreview?: string;
+    idempotencyRecordId?: string;
+    correlationId?: string;
+    requestId?: string;
+    commandId?: string;
+    detectedAtIso?: string;
+    hint?: string;
+    details?: string;
+    cause?: unknown;
+  }): IdempotencyReplayNotSupportedError;
+}
+declare class IdempotencyKeyMissingError extends IdempotencyError {
+  private constructor();
+  static detected(input: {
+    operation: string;
+    scope?: string;
+    entity?: string;
+    correlationId?: string;
+    requestId?: string;
+    commandId?: string;
+    detectedAtIso?: string;
+    hint?: string;
+    details?: string;
+    cause?: unknown;
+  }): IdempotencyKeyMissingError;
+}
+declare class IdempotencyInProgressError extends IdempotencyError {
+  private constructor();
+  static detected(input: {
+    operation: string;
+    scope?: string;
+    entity?: string;
+    key?: string;
+    keyHash?: string;
+    keyPreview?: string;
+    idempotencyRecordId?: string;
+    correlationId?: string;
+    requestId?: string;
+    commandId?: string;
+    detectedAtIso?: string;
+    hint?: string;
+    details?: string;
+    cause?: unknown;
+  }): IdempotencyInProgressError;
+}
+declare class IdempotencyPayloadMismatchError extends IdempotencyError {
+  private constructor();
+  static detected(input: {
+    operation: string;
+    scope?: string;
+    entity?: string;
+    key?: string;
+    keyHash?: string;
+    keyPreview?: string;
+    incomingPayloadHash?: string;
+    existingPayloadHash?: string;
+    idempotencyRecordId?: string;
+    correlationId?: string;
+    requestId?: string;
+    commandId?: string;
+    detectedAtIso?: string;
+    hint?: string;
+    details?: string;
+    cause?: unknown;
+  }): IdempotencyPayloadMismatchError;
+}
+declare class IdempotencyReplayNotSupportedError extends IdempotencyError {
+  private constructor();
+  static detected(input: {
+    operation: string;
+    scope?: string;
+    entity?: string;
+    key?: string;
+    keyHash?: string;
+    keyPreview?: string;
+    idempotencyRecordId?: string;
+    correlationId?: string;
+    requestId?: string;
+    commandId?: string;
+    detectedAtIso?: string;
+    hint?: string;
+    details?: string;
+    cause?: unknown;
+  }): IdempotencyReplayNotSupportedError;
+}
+//#endregion
+//#region src/core/errors/integration-error.d.ts
+type IntegrationErrorReason = "timeout" | "unreachable" | "bad_response" | "unknown";
+type IntegrationErrorMetadata = {
+  reason: IntegrationErrorReason;
+  provider: string;
+  operation: string;
+  startedAtIso: string;
+  durationMs: number;
+  detectedAtIso?: string;
+  correlationId?: string;
+  requestId?: string;
+  commandId?: string;
+  details?: string;
+  statusCode?: number;
+  responseCode?: string;
+};
+/**
+ * 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.
+ */
+declare class IntegrationError extends AppError {
+  readonly reason: IntegrationErrorReason;
+  private constructor();
+  /**
+   * 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: IntegrationErrorTimeoutOptions): IntegrationError;
+  /**
+   * The provider could not be reached at all (connection refused, DNS
+   * failure, network partition) — the request never landed.
+   */
+  static unreachable(options: IntegrationErrorEndpointOptions): IntegrationError;
+  /**
+   * 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: IntegrationErrorEndpointOptions): IntegrationError;
+}
+type IntegrationErrorBaseOptions = {
+  provider: string;
+  operation: string;
+  startedAtIso: string;
+  durationMs: number;
+  detectedAtIso?: string;
+  correlationId?: string;
+  requestId?: string;
+  commandId?: string;
+  details?: string;
+  statusCode?: number;
+  responseCode?: string;
+  cause?: unknown;
+  type?: string;
+  severity?: ErrorSeverity;
+  createdAtIso?: string;
+  publicMessage?: string;
+};
+type IntegrationErrorTimeoutOptions = IntegrationErrorBaseOptions;
+type IntegrationErrorEndpointOptions = IntegrationErrorBaseOptions;
+//#endregion
+//#region src/core/errors/legacy-incompatible-error.d.ts
+declare class LegacyIncompatibleError extends AppError {
+  constructor(message: string, context?: Record<string, unknown>, options?: AppErrorOptions);
+}
+//#endregion
+//#region src/core/errors/not-found-error.d.ts
+/**
+ * Raised when a requested resource does not exist. Maps naturally onto an HTTP
+ * 404 at the edge, but stays transport-agnostic here.
+ *
+ * The `resource` name builds the message (`"<resource> not found"`) and, with
+ * the optional lookup `criteria`, lands in the metadata so logs show *what* was
+ * searched for without the caller having to restate it in the message.
+ */
+declare class NotFoundError extends AppError {
+  /**
+   * @param resource - Human-readable name of the missing resource (e.g. `"Order"`).
+   * @param criteria - Optional lookup keys used in the search; recorded in
+   *   metadata to aid debugging. Avoid putting sensitive values here.
+   * @param options - Optional cause, correlation ids, and extra metadata.
+   */
+  constructor(resource: string, criteria?: Record<string, unknown>, options?: AppErrorOptions);
+}
+//#endregion
+//#region src/core/errors/serialization-error.d.ts
+type SerializationDirection = "serialize" | "deserialize";
+type SerializationFailureCategory = "invalid_json" | "invalid_shape" | "missing_field" | "unexpected_field" | "invalid_type" | "schema_version_missing" | "schema_version_unsupported" | "mapping_not_implemented" | "contract_mismatch" | "parse_failed" | "stringify_failed" | "unknown";
+type SerializationBoundary = "http_in" | "http_out" | "graphql_in" | "graphql_out" | "dto_to_domain" | "domain_to_dto" | "persistence_to_domain" | "domain_to_persistence" | "event_in" | "event_out" | "projection" | "unknown";
+/**
+ * Metadata shared by serialization/deserialization failures. Payload previews must be sanitized.
+ */
+type SerializationErrorMetadata = {
+  direction: SerializationDirection;
+  category: SerializationFailureCategory;
+  boundary: SerializationBoundary;
+  contract: string;
+  schemaVersion?: number | string;
+  path?: string;
+  payloadPreview?: string;
+  correlationId?: string;
+  requestId?: string;
+  commandId?: string;
+  hint?: string;
+  details?: string;
+};
+type SerializationErrorOptions = Omit<AppErrorOptions, "metadata"> & {
+  message: string;
+  code: string;
+  metadata: Omit<SerializationErrorMetadata, "direction" | "category">;
+  direction: SerializationDirection;
+  category: SerializationFailureCategory;
+};
+declare abstract class SerializationError extends AppError {
+  readonly direction: SerializationDirection;
+  readonly category: SerializationFailureCategory;
+  readonly boundary: SerializationBoundary;
+  readonly contract: string;
+  protected constructor(input: SerializationErrorOptions);
+}
+declare class SerializationInError extends SerializationError {
+  private constructor();
+  static failure(category: SerializationFailureCategory, metadata: Omit<SerializationErrorMetadata, "direction" | "category"> & {
+    cause?: unknown;
+  }): SerializationInError;
+}
+declare class SerializationOutError extends SerializationError {
+  private constructor();
+  static failure(category: SerializationFailureCategory, metadata: Omit<SerializationErrorMetadata, "direction" | "category"> & {
+    cause?: unknown;
+  }): SerializationOutError;
+}
+declare class SerializationCodes {
+  static code(direction: SerializationDirection, category: SerializationFailureCategory): string;
+}
+declare class SerializationMessages {
+  static message(direction: SerializationDirection, category: SerializationFailureCategory): string;
+}
+declare function safePreview(value: unknown, limit?: number): string | undefined;
+//#endregion
+//#region src/core/errors/temporal-error.d.ts
+type TemporalKind = "expired" | "not_yet_valid";
+type TemporalPrecision = "EXACT" | "ESTIMATED" | "UNKNOWN" | "APPROXIMATE";
+type TemporalErrorMetadata = {
+  resourceType: string;
+  resourceId?: string;
+  operation?: string;
+  validFromIso?: string | null;
+  validUntilIso?: string | null;
+  evaluatedAtIso: string;
+  policyId?: string;
+  precision?: TemporalPrecision;
+  hint?: string;
+  details?: string;
+  correlationId?: string;
+  requestId?: string;
+  commandId?: string;
+};
+type TemporalErrorOptions = {
+  message: string;
+  code: string;
+  kind: TemporalKind;
+  metadata: TemporalErrorMetadata;
+} & AppErrorOptions;
+declare abstract class TemporalError extends AppError {
+  readonly kind: TemporalKind;
+  readonly resourceType: string;
+  readonly evaluatedAtIso: string;
+  protected constructor(input: TemporalErrorOptions);
+}
+type TemporalCreationInput = TemporalErrorMetadata & Partial<Omit<AppErrorOptions, "metadata">> & {
+  cause?: unknown;
+};
+declare class ExpiredError extends TemporalError {
+  private constructor();
+  static detected(input: TemporalCreationInput): ExpiredError;
+}
+declare class NotYetValidError extends TemporalError {
+  private constructor();
+  static detected(input: TemporalCreationInput): NotYetValidError;
+}
+declare function evaluateTemporalWindow(input: {
+  validFromIso?: string | null;
+  validUntilIso?: string | null;
+  evaluatedAtIso: string;
+}): {
+  expired: boolean;
+  notYetValid: boolean;
+} | null;
+//#endregion
+//#region src/core/errors/unexpected-error.d.ts
+declare class UnexpectedError extends AppError {
+  constructor(message?: string, cause?: unknown, options?: Omit<AppErrorOptions, "cause">);
+}
+//#endregion
+//#region src/core/errors/validation-error.d.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`.
+ */
+declare class ValidationError extends 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: ValidationField, code: ValidationCode, message: string, options?: AppErrorOptions);
+}
+//#endregion
+export { serializationErrorCode as $, IdempotencyPayloadMismatchError as A, UniqueConstraintViolation as B, IntegrationErrorMetadata as C, IdempotencyFailureKind as D, IdempotencyErrorMetadata as E, AlreadyExistsError as F, AuthorizationErrorMetadata as G, translateUniqueViolationToDuplicate as H, ConflictError as I, AuthenticationError as J, AuthorizationErrorReason as K, ConflictErrorMetadata as L, payloadHash as M, sha256Hex as N, IdempotencyInProgressError as O, stableStringify as P, ErrorCodes as Q, ConflictKind as R, IntegrationError as S, IdempotencyError as T, BusinessRuleViolationError as U, UniqueConstraintViolationError as V, AuthorizationError as W, AuthenticationErrorReason as X, AuthenticationErrorMetadata as Y, assertJsonSafeMetadata as Z, SerializationMessages as _, TemporalError as a, NotFoundError as b, TemporalPrecision as c, SerializationCodes as d, SerializationDirection as f, SerializationInError as g, SerializationFailureCategory as h, NotYetValidError as i, IdempotencyReplayNotSupportedError as j, IdempotencyKeyMissingError as k, evaluateTemporalWindow as l, SerializationErrorMetadata as m, UnexpectedError as n, TemporalErrorMetadata as o, SerializationError as p, AuthorizationRequirement as q, ExpiredError as r, TemporalKind as s, ValidationError as t, SerializationBoundary as u, SerializationOutError as v, IntegrationErrorReason as w, LegacyIncompatibleError as x, safePreview as y, DuplicateError as z };
+//# sourceMappingURL=validation-error.d.cts.map