@sourceaxis/errors 0.1.0

package/README.md

@@ -0,0 +1,36 @@
+# @sourceaxis/errors
+
+Stable public error hierarchy for SourceAxis.
+
+## Responsibilities
+
+- Provide `SourceAxisError` as the base public error type.
+- Expose stable error codes, retryability, categories, severity, timestamps, diagnostics, and
+  serialization.
+- Provide typed subclasses for authentication, authorization, configuration, provider, repository,
+  transport, timeout, cancellation, validation, conflict, not-found, rate-limit, unsupported
+  capability, and unexpected failures.
+
+## Install
+
+```sh
+pnpm add @sourceaxis/errors
+```
+
+## Usage
+
+```ts
+import { SourceAxisError } from "@sourceaxis/errors";
+
+try {
+  await operation();
+} catch (error) {
+  if (error instanceof SourceAxisError) {
+    console.error(error.code, error.retryability, error.diagnostics);
+  } else {
+    throw error;
+  }
+}
+```
+
+Use `serialize()` or `toJSON()` for safe diagnostics and telemetry payloads.

package/dist/cjs/index.js

@@ -0,0 +1,363 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnexpectedError = exports.RepositoryError = exports.NotFoundError = exports.ConflictError = exports.AuthorizationError = exports.CapabilityNotSupportedError = exports.RateLimitError = exports.ProviderError = exports.AuthenticationError = exports.CancellationError = exports.TimeoutError = exports.TransportError = exports.ConfigurationError = exports.ValidationError = exports.SourceAxisError = exports.ErrorCodes = void 0;
+/**
+ * Stable public error codes. These codes are part of the compatibility contract.
+ */
+exports.ErrorCodes = {
+    Authentication: "SOURCEAXIS_AUTHENTICATION",
+    Authorization: "SOURCEAXIS_PERMISSION_DENIED",
+    Cancellation: "SOURCEAXIS_CANCELLED",
+    CapabilityNotSupported: "SOURCEAXIS_CAPABILITY_NOT_SUPPORTED",
+    Configuration: "SOURCEAXIS_CONFIGURATION",
+    Conflict: "SOURCEAXIS_CONFLICT",
+    NotFound: "SOURCEAXIS_NOT_FOUND",
+    Provider: "SOURCEAXIS_PROVIDER",
+    RateLimit: "SOURCEAXIS_RATE_LIMITED",
+    Repository: "SOURCEAXIS_REPOSITORY",
+    Timeout: "SOURCEAXIS_TIMEOUT",
+    Transport: "SOURCEAXIS_TRANSPORT",
+    Unexpected: "SOURCEAXIS_UNEXPECTED",
+    Validation: "SOURCEAXIS_VALIDATION"
+};
+const definitions = {
+    AuthenticationError: {
+        category: "authentication",
+        code: exports.ErrorCodes.Authentication,
+        retryability: "Never",
+        severity: "error"
+    },
+    CancellationError: {
+        category: "transport",
+        code: exports.ErrorCodes.Cancellation,
+        retryability: "Never",
+        severity: "info"
+    },
+    CapabilityNotSupportedError: {
+        category: "provider",
+        code: exports.ErrorCodes.CapabilityNotSupported,
+        retryability: "Never",
+        severity: "warning"
+    },
+    ConfigurationError: {
+        category: "configuration",
+        code: exports.ErrorCodes.Configuration,
+        retryability: "Never",
+        severity: "error"
+    },
+    ConflictError: {
+        category: "provider",
+        code: exports.ErrorCodes.Conflict,
+        retryability: "Maybe",
+        severity: "warning"
+    },
+    SourceAxisError: {
+        category: "unexpected",
+        code: exports.ErrorCodes.Unexpected,
+        retryability: "Never",
+        severity: "error"
+    },
+    NotFoundError: {
+        category: "provider",
+        code: exports.ErrorCodes.NotFound,
+        retryability: "Never",
+        severity: "warning"
+    },
+    AuthorizationError: {
+        category: "provider",
+        code: exports.ErrorCodes.Authorization,
+        retryability: "Never",
+        severity: "error"
+    },
+    ProviderError: {
+        category: "provider",
+        code: exports.ErrorCodes.Provider,
+        retryability: "Maybe",
+        severity: "error"
+    },
+    RateLimitError: {
+        category: "provider",
+        code: exports.ErrorCodes.RateLimit,
+        retryability: "Always",
+        severity: "warning"
+    },
+    RepositoryError: {
+        category: "repository",
+        code: exports.ErrorCodes.Repository,
+        retryability: "Maybe",
+        severity: "error"
+    },
+    TimeoutError: {
+        category: "transport",
+        code: exports.ErrorCodes.Timeout,
+        retryability: "Maybe",
+        severity: "warning"
+    },
+    TransportError: {
+        category: "transport",
+        code: exports.ErrorCodes.Transport,
+        retryability: "Maybe",
+        severity: "error"
+    },
+    UnexpectedError: {
+        category: "unexpected",
+        code: exports.ErrorCodes.Unexpected,
+        retryability: "Never",
+        severity: "critical"
+    },
+    ValidationError: {
+        category: "validation",
+        code: exports.ErrorCodes.Validation,
+        retryability: "Never",
+        severity: "warning"
+    }
+};
+/**
+ * Base class for every public SourceAxis error.
+ */
+class SourceAxisError extends Error {
+    /**
+     * Stable public error code.
+     */
+    code;
+    /**
+     * Retry guidance for callers and retry middleware.
+     */
+    retryability;
+    /**
+     * Provider-neutral error category.
+     */
+    category;
+    /**
+     * Diagnostic severity.
+     */
+    severity;
+    /**
+     * ISO-8601 timestamp captured when the error is created.
+     */
+    timestamp;
+    /**
+     * Safe structured diagnostic context.
+     */
+    diagnostics;
+    /**
+     * Immutable error metadata.
+     */
+    metadata;
+    constructor(message, options = {}) {
+        const definition = getDefinition(new.target.name);
+        super(message, createErrorOptions(options.cause));
+        Object.setPrototypeOf(this, new.target.prototype);
+        this.name = new.target.name;
+        this.code = definition.code;
+        this.retryability = options.retryability ?? definition.retryability;
+        this.category = definition.category;
+        this.severity = options.severity ?? definition.severity;
+        this.timestamp = normalizeTimestamp(options.timestamp);
+        this.diagnostics = freezeDiagnostics(options.diagnostics);
+        this.metadata = deepFreeze({
+            category: this.category,
+            code: this.code,
+            retryability: this.retryability,
+            severity: this.severity,
+            timestamp: this.timestamp
+        });
+        if (Error.captureStackTrace !== undefined) {
+            Error.captureStackTrace(this, new.target);
+        }
+        Object.freeze(this);
+    }
+    /**
+     * Returns a deterministic, safe representation suitable for diagnostics and telemetry.
+     */
+    toJSON() {
+        const serialized = {
+            category: this.category,
+            code: this.code,
+            diagnostics: this.diagnostics,
+            message: this.message,
+            name: this.name,
+            retryability: this.retryability,
+            severity: this.severity,
+            timestamp: this.timestamp
+        };
+        const cause = serializeCause(this.cause);
+        if (cause !== undefined) {
+            serialized.cause = cause;
+        }
+        return deepFreeze(serialized);
+    }
+    /**
+     * Returns the canonical serialized representation.
+     */
+    serialize() {
+        return this.toJSON();
+    }
+}
+exports.SourceAxisError = SourceAxisError;
+/**
+ * Validation failure detected before an operation executes.
+ */
+class ValidationError extends SourceAxisError {
+    constructor(message, options = {}) {
+        super(message, options);
+    }
+}
+exports.ValidationError = ValidationError;
+/**
+ * Invalid or missing SourceAxis configuration.
+ */
+class ConfigurationError extends SourceAxisError {
+    constructor(message, options = {}) {
+        super(message, options);
+    }
+}
+exports.ConfigurationError = ConfigurationError;
+/**
+ * Transport-neutral execution failure.
+ */
+class TransportError extends SourceAxisError {
+    constructor(message, options = {}) {
+        super(message, options);
+    }
+}
+exports.TransportError = TransportError;
+/**
+ * Request execution exceeded an allowed duration.
+ */
+class TimeoutError extends TransportError {
+    constructor(message, options = {}) {
+        super(message, options);
+    }
+}
+exports.TimeoutError = TimeoutError;
+/**
+ * Operation was intentionally interrupted.
+ */
+class CancellationError extends TransportError {
+    constructor(message, options = {}) {
+        super(message, options);
+    }
+}
+exports.CancellationError = CancellationError;
+/**
+ * Authentication failure.
+ */
+class AuthenticationError extends SourceAxisError {
+    constructor(message, options = {}) {
+        super(message, options);
+    }
+}
+exports.AuthenticationError = AuthenticationError;
+/**
+ * Provider-neutral provider failure.
+ */
+class ProviderError extends SourceAxisError {
+    constructor(message, options = {}) {
+        super(message, options);
+    }
+}
+exports.ProviderError = ProviderError;
+/**
+ * Provider rate limit failure.
+ */
+class RateLimitError extends ProviderError {
+    constructor(message, options = {}) {
+        super(message, options);
+    }
+}
+exports.RateLimitError = RateLimitError;
+/**
+ * Requested provider capability is not supported.
+ */
+class CapabilityNotSupportedError extends ProviderError {
+    constructor(message, options = {}) {
+        super(message, options);
+    }
+}
+exports.CapabilityNotSupportedError = CapabilityNotSupportedError;
+/**
+ * Provider denied permission for the requested operation.
+ */
+class AuthorizationError extends ProviderError {
+    constructor(message, options = {}) {
+        super(message, options);
+    }
+}
+exports.AuthorizationError = AuthorizationError;
+/**
+ * Provider reported a conflict for the requested operation.
+ */
+class ConflictError extends ProviderError {
+    constructor(message, options = {}) {
+        super(message, options);
+    }
+}
+exports.ConflictError = ConflictError;
+/**
+ * Provider or repository resource was not found.
+ */
+class NotFoundError extends ProviderError {
+    constructor(message, options = {}) {
+        super(message, options);
+    }
+}
+exports.NotFoundError = NotFoundError;
+/**
+ * Repository lifecycle or repository state failure.
+ */
+class RepositoryError extends SourceAxisError {
+    constructor(message, options = {}) {
+        super(message, options);
+    }
+}
+exports.RepositoryError = RepositoryError;
+/**
+ * Internal defect or unforeseen runtime condition.
+ */
+class UnexpectedError extends SourceAxisError {
+    constructor(message, options = {}) {
+        super(message, options);
+    }
+}
+exports.UnexpectedError = UnexpectedError;
+function getDefinition(name) {
+    return definitions[name] ?? definitions.SourceAxisError;
+}
+function createErrorOptions(cause) {
+    return cause === undefined ? undefined : { cause };
+}
+function normalizeTimestamp(timestamp) {
+    if (timestamp instanceof Date) {
+        return timestamp.toISOString();
+    }
+    return timestamp ?? new Date().toISOString();
+}
+function freezeDiagnostics(diagnostics) {
+    return deepFreeze(diagnostics ?? {});
+}
+function serializeCause(cause) {
+    if (cause instanceof SourceAxisError) {
+        return cause.toJSON();
+    }
+    if (cause instanceof Error) {
+        return deepFreeze({ name: cause.name });
+    }
+    if (cause === undefined) {
+        return undefined;
+    }
+    return deepFreeze({ name: typeof cause });
+}
+function deepFreeze(value) {
+    if (value === null || (typeof value !== "object" && typeof value !== "function")) {
+        return value;
+    }
+    for (const key of Reflect.ownKeys(value)) {
+        const child = value[key];
+        if (child !== null && (typeof child === "object" || typeof child === "function")) {
+            deepFreeze(child);
+        }
+    }
+    return Object.freeze(value);
+}
+//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"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"}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/esm/index.d.ts

@@ -0,0 +1,262 @@
+/**
+ * Retry guidance exposed by every public SourceAxis error.
+ */
+export type ErrorRetryability = "Never" | "Maybe" | "Always";
+/**
+ * Stable public error codes. These codes are part of the compatibility contract.
+ */
+export declare const ErrorCodes: {
+    readonly Authentication: "SOURCEAXIS_AUTHENTICATION";
+    readonly Authorization: "SOURCEAXIS_PERMISSION_DENIED";
+    readonly Cancellation: "SOURCEAXIS_CANCELLED";
+    readonly CapabilityNotSupported: "SOURCEAXIS_CAPABILITY_NOT_SUPPORTED";
+    readonly Configuration: "SOURCEAXIS_CONFIGURATION";
+    readonly Conflict: "SOURCEAXIS_CONFLICT";
+    readonly NotFound: "SOURCEAXIS_NOT_FOUND";
+    readonly Provider: "SOURCEAXIS_PROVIDER";
+    readonly RateLimit: "SOURCEAXIS_RATE_LIMITED";
+    readonly Repository: "SOURCEAXIS_REPOSITORY";
+    readonly Timeout: "SOURCEAXIS_TIMEOUT";
+    readonly Transport: "SOURCEAXIS_TRANSPORT";
+    readonly Unexpected: "SOURCEAXIS_UNEXPECTED";
+    readonly Validation: "SOURCEAXIS_VALIDATION";
+};
+/**
+ * Stable public error code.
+ */
+export type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+/**
+ * Public classification for SourceAxis errors.
+ */
+export type ErrorCategory = "authentication" | "configuration" | "provider" | "repository" | "transport" | "unexpected" | "validation";
+/**
+ * Diagnostic severity for a SourceAxis error.
+ */
+export type ErrorSeverity = "debug" | "info" | "warning" | "error" | "critical";
+/**
+ * JSON-safe primitive value accepted in diagnostics.
+ */
+export type DiagnosticPrimitive = string | number | boolean | null;
+/**
+ * JSON-safe diagnostic value accepted in public errors.
+ */
+export type DiagnosticValue = DiagnosticPrimitive | readonly DiagnosticValue[] | {
+    readonly [key: string]: DiagnosticValue;
+};
+/**
+ * Operation-level diagnostic context.
+ */
+export type OperationDiagnostics = Readonly<{
+    operation?: string;
+    capability?: string;
+    retryCount?: number;
+    elapsedMs?: number;
+    correlationId?: string;
+}>;
+/**
+ * Repository-level diagnostic context.
+ */
+export type RepositoryDiagnostics = Readonly<{
+    provider?: string;
+    repository?: string;
+    reference?: string;
+    path?: string;
+}>;
+/**
+ * Provider-neutral diagnostic context.
+ */
+export type ProviderDiagnostics = Readonly<{
+    provider?: string;
+    requestId?: string;
+    activityId?: string;
+    status?: number;
+    providerCode?: string;
+}>;
+/**
+ * Transport-neutral diagnostic context.
+ */
+export type TransportDiagnostics = Readonly<{
+    transport?: string;
+    timeoutMs?: number;
+    cancelled?: boolean;
+    requestMethod?: string;
+    requestUrl?: string;
+}>;
+/**
+ * Safe structured diagnostic context exposed by SourceAxis errors.
+ */
+export type ErrorDiagnostics = Readonly<{
+    operation?: OperationDiagnostics;
+    repository?: RepositoryDiagnostics;
+    provider?: ProviderDiagnostics;
+    transport?: TransportDiagnostics;
+    extra?: Readonly<Record<string, DiagnosticValue>>;
+}>;
+/**
+ * Immutable metadata exposed by every public SourceAxis error.
+ */
+export type ErrorMetadata = Readonly<{
+    code: ErrorCode;
+    retryability: ErrorRetryability;
+    category: ErrorCategory;
+    severity: ErrorSeverity;
+    timestamp: string;
+}>;
+/**
+ * Constructor options shared by every public SourceAxis error.
+ */
+export type SourceAxisErrorOptions = Readonly<{
+    cause?: unknown;
+    diagnostics?: ErrorDiagnostics;
+    retryability?: ErrorRetryability;
+    severity?: ErrorSeverity;
+    timestamp?: Date | string;
+}>;
+/**
+ * Safe serialized representation of a cause.
+ */
+export type SerializedCause = Readonly<{
+    name: string;
+    code?: ErrorCode;
+}>;
+/**
+ * Safe serialized representation of a SourceAxis error.
+ */
+export type SerializedSourceAxisError = Readonly<{
+    name: string;
+    message: string;
+    code: ErrorCode;
+    retryability: ErrorRetryability;
+    category: ErrorCategory;
+    severity: ErrorSeverity;
+    timestamp: string;
+    diagnostics: ErrorDiagnostics;
+    cause?: SerializedSourceAxisError | SerializedCause;
+}>;
+/**
+ * Base class for every public SourceAxis error.
+ */
+export declare class SourceAxisError extends Error {
+    /**
+     * Stable public error code.
+     */
+    readonly code: ErrorCode;
+    /**
+     * Retry guidance for callers and retry middleware.
+     */
+    readonly retryability: ErrorRetryability;
+    /**
+     * Provider-neutral error category.
+     */
+    readonly category: ErrorCategory;
+    /**
+     * Diagnostic severity.
+     */
+    readonly severity: ErrorSeverity;
+    /**
+     * ISO-8601 timestamp captured when the error is created.
+     */
+    readonly timestamp: string;
+    /**
+     * Safe structured diagnostic context.
+     */
+    readonly diagnostics: ErrorDiagnostics;
+    /**
+     * Immutable error metadata.
+     */
+    readonly metadata: ErrorMetadata;
+    constructor(message: string, options?: SourceAxisErrorOptions);
+    /**
+     * Returns a deterministic, safe representation suitable for diagnostics and telemetry.
+     */
+    toJSON(): SerializedSourceAxisError;
+    /**
+     * Returns the canonical serialized representation.
+     */
+    serialize(): SerializedSourceAxisError;
+}
+/**
+ * Validation failure detected before an operation executes.
+ */
+export declare class ValidationError extends SourceAxisError {
+    constructor(message: string, options?: SourceAxisErrorOptions);
+}
+/**
+ * Invalid or missing SourceAxis configuration.
+ */
+export declare class ConfigurationError extends SourceAxisError {
+    constructor(message: string, options?: SourceAxisErrorOptions);
+}
+/**
+ * Transport-neutral execution failure.
+ */
+export declare class TransportError extends SourceAxisError {
+    constructor(message: string, options?: SourceAxisErrorOptions);
+}
+/**
+ * Request execution exceeded an allowed duration.
+ */
+export declare class TimeoutError extends TransportError {
+    constructor(message: string, options?: SourceAxisErrorOptions);
+}
+/**
+ * Operation was intentionally interrupted.
+ */
+export declare class CancellationError extends TransportError {
+    constructor(message: string, options?: SourceAxisErrorOptions);
+}
+/**
+ * Authentication failure.
+ */
+export declare class AuthenticationError extends SourceAxisError {
+    constructor(message: string, options?: SourceAxisErrorOptions);
+}
+/**
+ * Provider-neutral provider failure.
+ */
+export declare class ProviderError extends SourceAxisError {
+    constructor(message: string, options?: SourceAxisErrorOptions);
+}
+/**
+ * Provider rate limit failure.
+ */
+export declare class RateLimitError extends ProviderError {
+    constructor(message: string, options?: SourceAxisErrorOptions);
+}
+/**
+ * Requested provider capability is not supported.
+ */
+export declare class CapabilityNotSupportedError extends ProviderError {
+    constructor(message: string, options?: SourceAxisErrorOptions);
+}
+/**
+ * Provider denied permission for the requested operation.
+ */
+export declare class AuthorizationError extends ProviderError {
+    constructor(message: string, options?: SourceAxisErrorOptions);
+}
+/**
+ * Provider reported a conflict for the requested operation.
+ */
+export declare class ConflictError extends ProviderError {
+    constructor(message: string, options?: SourceAxisErrorOptions);
+}
+/**
+ * Provider or repository resource was not found.
+ */
+export declare class NotFoundError extends ProviderError {
+    constructor(message: string, options?: SourceAxisErrorOptions);
+}
+/**
+ * Repository lifecycle or repository state failure.
+ */
+export declare class RepositoryError extends SourceAxisError {
+    constructor(message: string, options?: SourceAxisErrorOptions);
+}
+/**
+ * Internal defect or unforeseen runtime condition.
+ */
+export declare class UnexpectedError extends SourceAxisError {
+    constructor(message: string, options?: SourceAxisErrorOptions);
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}

package/dist/esm/index.js

@@ -0,0 +1,344 @@
+/**
+ * Stable public error codes. These codes are part of the compatibility contract.
+ */
+export const ErrorCodes = {
+    Authentication: "SOURCEAXIS_AUTHENTICATION",
+    Authorization: "SOURCEAXIS_PERMISSION_DENIED",
+    Cancellation: "SOURCEAXIS_CANCELLED",
+    CapabilityNotSupported: "SOURCEAXIS_CAPABILITY_NOT_SUPPORTED",
+    Configuration: "SOURCEAXIS_CONFIGURATION",
+    Conflict: "SOURCEAXIS_CONFLICT",
+    NotFound: "SOURCEAXIS_NOT_FOUND",
+    Provider: "SOURCEAXIS_PROVIDER",
+    RateLimit: "SOURCEAXIS_RATE_LIMITED",
+    Repository: "SOURCEAXIS_REPOSITORY",
+    Timeout: "SOURCEAXIS_TIMEOUT",
+    Transport: "SOURCEAXIS_TRANSPORT",
+    Unexpected: "SOURCEAXIS_UNEXPECTED",
+    Validation: "SOURCEAXIS_VALIDATION"
+};
+const definitions = {
+    AuthenticationError: {
+        category: "authentication",
+        code: ErrorCodes.Authentication,
+        retryability: "Never",
+        severity: "error"
+    },
+    CancellationError: {
+        category: "transport",
+        code: ErrorCodes.Cancellation,
+        retryability: "Never",
+        severity: "info"
+    },
+    CapabilityNotSupportedError: {
+        category: "provider",
+        code: ErrorCodes.CapabilityNotSupported,
+        retryability: "Never",
+        severity: "warning"
+    },
+    ConfigurationError: {
+        category: "configuration",
+        code: ErrorCodes.Configuration,
+        retryability: "Never",
+        severity: "error"
+    },
+    ConflictError: {
+        category: "provider",
+        code: ErrorCodes.Conflict,
+        retryability: "Maybe",
+        severity: "warning"
+    },
+    SourceAxisError: {
+        category: "unexpected",
+        code: ErrorCodes.Unexpected,
+        retryability: "Never",
+        severity: "error"
+    },
+    NotFoundError: {
+        category: "provider",
+        code: ErrorCodes.NotFound,
+        retryability: "Never",
+        severity: "warning"
+    },
+    AuthorizationError: {
+        category: "provider",
+        code: ErrorCodes.Authorization,
+        retryability: "Never",
+        severity: "error"
+    },
+    ProviderError: {
+        category: "provider",
+        code: ErrorCodes.Provider,
+        retryability: "Maybe",
+        severity: "error"
+    },
+    RateLimitError: {
+        category: "provider",
+        code: ErrorCodes.RateLimit,
+        retryability: "Always",
+        severity: "warning"
+    },
+    RepositoryError: {
+        category: "repository",
+        code: ErrorCodes.Repository,
+        retryability: "Maybe",
+        severity: "error"
+    },
+    TimeoutError: {
+        category: "transport",
+        code: ErrorCodes.Timeout,
+        retryability: "Maybe",
+        severity: "warning"
+    },
+    TransportError: {
+        category: "transport",
+        code: ErrorCodes.Transport,
+        retryability: "Maybe",
+        severity: "error"
+    },
+    UnexpectedError: {
+        category: "unexpected",
+        code: ErrorCodes.Unexpected,
+        retryability: "Never",
+        severity: "critical"
+    },
+    ValidationError: {
+        category: "validation",
+        code: ErrorCodes.Validation,
+        retryability: "Never",
+        severity: "warning"
+    }
+};
+/**
+ * Base class for every public SourceAxis error.
+ */
+export class SourceAxisError extends Error {
+    /**
+     * Stable public error code.
+     */
+    code;
+    /**
+     * Retry guidance for callers and retry middleware.
+     */
+    retryability;
+    /**
+     * Provider-neutral error category.
+     */
+    category;
+    /**
+     * Diagnostic severity.
+     */
+    severity;
+    /**
+     * ISO-8601 timestamp captured when the error is created.
+     */
+    timestamp;
+    /**
+     * Safe structured diagnostic context.
+     */
+    diagnostics;
+    /**
+     * Immutable error metadata.
+     */
+    metadata;
+    constructor(message, options = {}) {
+        const definition = getDefinition(new.target.name);
+        super(message, createErrorOptions(options.cause));
+        Object.setPrototypeOf(this, new.target.prototype);
+        this.name = new.target.name;
+        this.code = definition.code;
+        this.retryability = options.retryability ?? definition.retryability;
+        this.category = definition.category;
+        this.severity = options.severity ?? definition.severity;
+        this.timestamp = normalizeTimestamp(options.timestamp);
+        this.diagnostics = freezeDiagnostics(options.diagnostics);
+        this.metadata = deepFreeze({
+            category: this.category,
+            code: this.code,
+            retryability: this.retryability,
+            severity: this.severity,
+            timestamp: this.timestamp
+        });
+        if (Error.captureStackTrace !== undefined) {
+            Error.captureStackTrace(this, new.target);
+        }
+        Object.freeze(this);
+    }
+    /**
+     * Returns a deterministic, safe representation suitable for diagnostics and telemetry.
+     */
+    toJSON() {
+        const serialized = {
+            category: this.category,
+            code: this.code,
+            diagnostics: this.diagnostics,
+            message: this.message,
+            name: this.name,
+            retryability: this.retryability,
+            severity: this.severity,
+            timestamp: this.timestamp
+        };
+        const cause = serializeCause(this.cause);
+        if (cause !== undefined) {
+            serialized.cause = cause;
+        }
+        return deepFreeze(serialized);
+    }
+    /**
+     * Returns the canonical serialized representation.
+     */
+    serialize() {
+        return this.toJSON();
+    }
+}
+/**
+ * Validation failure detected before an operation executes.
+ */
+export class ValidationError extends SourceAxisError {
+    constructor(message, options = {}) {
+        super(message, options);
+    }
+}
+/**
+ * Invalid or missing SourceAxis configuration.
+ */
+export class ConfigurationError extends SourceAxisError {
+    constructor(message, options = {}) {
+        super(message, options);
+    }
+}
+/**
+ * Transport-neutral execution failure.
+ */
+export class TransportError extends SourceAxisError {
+    constructor(message, options = {}) {
+        super(message, options);
+    }
+}
+/**
+ * Request execution exceeded an allowed duration.
+ */
+export class TimeoutError extends TransportError {
+    constructor(message, options = {}) {
+        super(message, options);
+    }
+}
+/**
+ * Operation was intentionally interrupted.
+ */
+export class CancellationError extends TransportError {
+    constructor(message, options = {}) {
+        super(message, options);
+    }
+}
+/**
+ * Authentication failure.
+ */
+export class AuthenticationError extends SourceAxisError {
+    constructor(message, options = {}) {
+        super(message, options);
+    }
+}
+/**
+ * Provider-neutral provider failure.
+ */
+export class ProviderError extends SourceAxisError {
+    constructor(message, options = {}) {
+        super(message, options);
+    }
+}
+/**
+ * Provider rate limit failure.
+ */
+export class RateLimitError extends ProviderError {
+    constructor(message, options = {}) {
+        super(message, options);
+    }
+}
+/**
+ * Requested provider capability is not supported.
+ */
+export class CapabilityNotSupportedError extends ProviderError {
+    constructor(message, options = {}) {
+        super(message, options);
+    }
+}
+/**
+ * Provider denied permission for the requested operation.
+ */
+export class AuthorizationError extends ProviderError {
+    constructor(message, options = {}) {
+        super(message, options);
+    }
+}
+/**
+ * Provider reported a conflict for the requested operation.
+ */
+export class ConflictError extends ProviderError {
+    constructor(message, options = {}) {
+        super(message, options);
+    }
+}
+/**
+ * Provider or repository resource was not found.
+ */
+export class NotFoundError extends ProviderError {
+    constructor(message, options = {}) {
+        super(message, options);
+    }
+}
+/**
+ * Repository lifecycle or repository state failure.
+ */
+export class RepositoryError extends SourceAxisError {
+    constructor(message, options = {}) {
+        super(message, options);
+    }
+}
+/**
+ * Internal defect or unforeseen runtime condition.
+ */
+export class UnexpectedError extends SourceAxisError {
+    constructor(message, options = {}) {
+        super(message, options);
+    }
+}
+function getDefinition(name) {
+    return definitions[name] ?? definitions.SourceAxisError;
+}
+function createErrorOptions(cause) {
+    return cause === undefined ? undefined : { cause };
+}
+function normalizeTimestamp(timestamp) {
+    if (timestamp instanceof Date) {
+        return timestamp.toISOString();
+    }
+    return timestamp ?? new Date().toISOString();
+}
+function freezeDiagnostics(diagnostics) {
+    return deepFreeze(diagnostics ?? {});
+}
+function serializeCause(cause) {
+    if (cause instanceof SourceAxisError) {
+        return cause.toJSON();
+    }
+    if (cause instanceof Error) {
+        return deepFreeze({ name: cause.name });
+    }
+    if (cause === undefined) {
+        return undefined;
+    }
+    return deepFreeze({ name: typeof cause });
+}
+function deepFreeze(value) {
+    if (value === null || (typeof value !== "object" && typeof value !== "function")) {
+        return value;
+    }
+    for (const key of Reflect.ownKeys(value)) {
+        const child = value[key];
+        if (child !== null && (typeof child === "object" || typeof child === "function")) {
+            deepFreeze(child);
+        }
+    }
+    return Object.freeze(value);
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@sourceaxis/errors",
+  "version": "0.1.0",
+  "description": "Canonical SourceAxis public error hierarchy and serialization model.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js",
+      "default": "./dist/esm/index.js"
+    }
+  },
+  "types": "./dist/esm/index.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.esm.json && node ../../scripts/build/build-cjs.mjs .",
+    "test": "vitest run --config vitest.config.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mriduldey/source-axis.git",
+    "directory": "packages/errors"
+  },
+  "bugs": {
+    "url": "https://github.com/mriduldey/source-axis/issues"
+  },
+  "homepage": "https://github.com/mriduldey/source-axis#readme",
+  "keywords": [
+    "git",
+    "github",
+    "sdk",
+    "typescript",
+    "provider-neutral"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}