hazo_core 1.0.0

package/dist/context/server.js

@@ -0,0 +1,52 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { registerSingleton, getSingleton } from '../singleton/index.js';
+import { generateRequestId } from '../utils/index.js';
+/**
+ * The AsyncLocalStorage instance is registered as a singleton on globalThis so that
+ * even if multiple copies of hazo_core end up in the module graph, they all share the
+ * same storage — ensuring correlation IDs flow correctly across the entire suite.
+ */
+const storage = getSingleton('hazo_core:context_als') ??
+    registerSingleton('hazo_core:context_als', new AsyncLocalStorage());
+/**
+ * Expose the ALS on globalThis so HazoError's constructor can lazily read the
+ * correlationId without creating a circular import dependency.
+ */
+globalThis['__hazo_core_context_store__'] = storage;
+/**
+ * Run `fn` within a new context that merges `values` on top of the parent context.
+ *
+ * Merge rules:
+ * 1. Parent context fields are inherited unless explicitly overridden by `values`.
+ * 2. `correlationId` is generated if neither `values` nor parent provides one.
+ *
+ * This means a child span always carries the parent's correlationId unless the caller
+ * explicitly wants to start a new correlation boundary.
+ */
+export function withContext(values, fn) {
+    const parent = storage.getStore();
+    const merged = {
+        // Start with parent fields
+        ...parent,
+        // Override with provided values
+        ...values,
+        // Ensure correlationId is always set — prefer explicit > parent > generated
+        correlationId: values.correlationId ?? parent?.correlationId ?? generateRequestId(),
+    };
+    return storage.run(merged, fn);
+}
+/**
+ * Read the current context, if any.
+ * Returns undefined when called outside a withContext() scope.
+ */
+export function getContext() {
+    return storage.getStore();
+}
+/**
+ * Convenience accessor for the most-commonly-needed context field.
+ * Returns undefined when called outside a withContext() scope.
+ */
+export function getCorrelationId() {
+    return storage.getStore()?.correlationId;
+}
+//# sourceMappingURL=server.js.map

package/dist/context/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/context/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAExE,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEtD;;;;GAIG;AACH,MAAM,OAAO,GACX,YAAY,CAAiC,uBAAuB,CAAC;IACrE,iBAAiB,CAAC,uBAAuB,EAAE,IAAI,iBAAiB,EAAe,CAAC,CAAC;AAEnF;;;GAGG;AACF,UAAsC,CAAC,6BAA6B,CAAC,GAAG,OAAO,CAAC;AAEjF;;;;;;;;;GASG;AACH,MAAM,UAAU,WAAW,CAAI,MAA4B,EAAE,EAAW;IACtE,MAAM,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAElC,MAAM,MAAM,GAAgB;QAC1B,2BAA2B;QAC3B,GAAG,MAAM;QACT,gCAAgC;QAChC,GAAG,MAAM;QACT,4EAA4E;QAC5E,aAAa,EACX,MAAM,CAAC,aAAa,IAAI,MAAM,EAAE,aAAa,IAAI,iBAAiB,EAAE;KACvE,CAAC;IAEF,OAAO,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AACjC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU;IACxB,OAAO,OAAO,CAAC,QAAQ,EAAE,CAAC;AAC5B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB;IAC9B,OAAO,OAAO,CAAC,QAAQ,EAAE,EAAE,aAAa,CAAC;AAC3C,CAAC"}

package/dist/context/types.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Ambient request/operation context propagated via AsyncLocalStorage (server)
+ * or a mutable ref (browser).
+ *
+ * This interface is additive: new fields can be added without breaking existing callers.
+ * Consumers should always check existence of optional fields before accessing them.
+ */
+export interface HazoContext {
+    /** Correlation ID tying together all log entries and error reports for this request/operation */
+    correlationId: string;
+    /** Authenticated user ID — set by hazo_auth middleware when a session is present */
+    userId?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/context/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/context/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,iGAAiG;IACjG,aAAa,EAAE,MAAM,CAAC;IACtB,oFAAoF;IACpF,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}

package/dist/context/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/context/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/context/types.ts"],"names":[],"mappings":""}

package/dist/debug/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * hazo_core debug factory — wraps hazo_debug and injects correlationId.
+ * Returns a complete no-op when hazo_debug is not installed.
+ *
+ * Per architecture.md §10 and D-007.
+ */
+export interface HazoCoreDebug {
+    /** Log a debug event with optional payload data. */
+    log(namespace: string, data?: unknown): void;
+}
+/**
+ * Create a debug instance for a hazo package.
+ *
+ * When hazo_debug is installed and exposes createDebug, wraps it and injects
+ * the current correlationId into every log call.
+ *
+ * When hazo_debug is absent or has no createDebug export, returns a no-op.
+ */
+export declare function createDebug(pkg: string): HazoCoreDebug;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/debug/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAQH,MAAM,WAAW,aAAa;IAC5B,oDAAoD;IACpD,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CAC9C;AAkED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,CAUtD"}

package/dist/debug/index.js

@@ -0,0 +1,78 @@
+/**
+ * hazo_core debug factory — wraps hazo_debug and injects correlationId.
+ * Returns a complete no-op when hazo_debug is not installed.
+ *
+ * Per architecture.md §10 and D-007.
+ */
+import { createRequire } from 'node:module';
+// ---------------------------------------------------------------------------
+// Detect hazo_debug at module init time
+// ---------------------------------------------------------------------------
+const _require = createRequire(import.meta.url);
+let hazoDebugModule = null;
+try {
+    hazoDebugModule = _require('hazo_debug');
+}
+catch {
+    // hazo_debug not installed — use no-op fallback
+}
+// ---------------------------------------------------------------------------
+// Resolve correlationId lazily (same pattern as logger/index.ts)
+// ---------------------------------------------------------------------------
+function getCorrelationIdLazy() {
+    try {
+        const store = globalThis['__hazo_core_context_store__'];
+        if (store && typeof store === 'object' && 'getStore' in store) {
+            const ctx = store.getStore();
+            return ctx?.['correlationId'];
+        }
+    }
+    catch {
+        // Ignore
+    }
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// No-op fallback
+// ---------------------------------------------------------------------------
+const noopDebug = {
+    log: () => undefined,
+};
+// ---------------------------------------------------------------------------
+// hazo_debug wrapper
+// ---------------------------------------------------------------------------
+function makeWrappedDebug(inner) {
+    return {
+        log: (namespace, data) => {
+            const correlationId = getCorrelationIdLazy();
+            const enriched = data !== null && typeof data === 'object' && !Array.isArray(data)
+                ? { ...data, correlationId }
+                : { data, correlationId };
+            inner.log(namespace, enriched);
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Public factory
+// ---------------------------------------------------------------------------
+/**
+ * Create a debug instance for a hazo package.
+ *
+ * When hazo_debug is installed and exposes createDebug, wraps it and injects
+ * the current correlationId into every log call.
+ *
+ * When hazo_debug is absent or has no createDebug export, returns a no-op.
+ */
+export function createDebug(pkg) {
+    if (hazoDebugModule && typeof hazoDebugModule.createDebug === 'function') {
+        try {
+            const inner = hazoDebugModule.createDebug(pkg);
+            return makeWrappedDebug(inner);
+        }
+        catch {
+            // Fall through to no-op
+        }
+    }
+    return noopDebug;
+}
+//# sourceMappingURL=index.js.map

package/dist/debug/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/debug/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAW5C,8EAA8E;AAC9E,wCAAwC;AACxC,8EAA8E;AAE9E,MAAM,QAAQ,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAOhD,IAAI,eAAe,GAA2B,IAAI,CAAC;AACnD,IAAI,CAAC;IACH,eAAe,GAAG,QAAQ,CAAC,YAAY,CAAoB,CAAC;AAC9D,CAAC;AAAC,MAAM,CAAC;IACP,gDAAgD;AAClD,CAAC;AAED,8EAA8E;AAC9E,iEAAiE;AACjE,8EAA8E;AAE9E,SAAS,oBAAoB;IAC3B,IAAI,CAAC;QACH,MAAM,KAAK,GAAI,UAAsC,CAAC,6BAA6B,CAAC,CAAC;QACrF,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,UAAU,IAAI,KAAK,EAAE,CAAC;YAC9D,MAAM,GAAG,GAAI,KAA6D,CAAC,QAAQ,EAAE,CAAC;YACtF,OAAO,GAAG,EAAE,CAAC,eAAe,CAAuB,CAAC;QACtD,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,SAAS;IACX,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,8EAA8E;AAC9E,iBAAiB;AACjB,8EAA8E;AAE9E,MAAM,SAAS,GAAkB;IAC/B,GAAG,EAAE,GAAG,EAAE,CAAC,SAAS;CACrB,CAAC;AAEF,8EAA8E;AAC9E,qBAAqB;AACrB,8EAA8E;AAE9E,SAAS,gBAAgB,CAAC,KAAoB;IAC5C,OAAO;QACL,GAAG,EAAE,CAAC,SAAS,EAAE,IAAI,EAAE,EAAE;YACvB,MAAM,aAAa,GAAG,oBAAoB,EAAE,CAAC;YAC7C,MAAM,QAAQ,GACZ,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;gBAC/D,CAAC,CAAC,EAAE,GAAI,IAAgC,EAAE,aAAa,EAAE;gBACzD,CAAC,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC;YAC9B,KAAK,CAAC,GAAG,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;QACjC,CAAC;KACF,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,iBAAiB;AACjB,8EAA8E;AAE9E;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,GAAW;IACrC,IAAI,eAAe,IAAI,OAAO,eAAe,CAAC,WAAW,KAAK,UAAU,EAAE,CAAC;QACzE,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,eAAe,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;YAC/C,OAAO,gBAAgB,CAAC,KAAK,CAAC,CAAC;QACjC,CAAC;QAAC,MAAM,CAAC;YACP,wBAAwB;QAC1B,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/errors/auth.d.ts

@@ -0,0 +1,14 @@
+import { HazoError, type HazoErrorOptions } from './base.js';
+export interface HazoAuthErrorOptions extends Omit<HazoErrorOptions, 'httpStatus' | 'retryable'> {
+    /**
+     * When true, sets httpStatus to 403 and uses the _FORBIDDEN code prefix.
+     * Default false → 401 with _UNAUTHORIZED prefix.
+     */
+    forbidden?: boolean;
+}
+export declare class HazoAuthError extends HazoError {
+    readonly forbidden: boolean;
+    constructor(opts: HazoAuthErrorOptions);
+    toUserMessage(): string;
+}
+//# sourceMappingURL=auth.d.ts.map

package/dist/errors/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/errors/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAE7D,MAAM,WAAW,oBAAqB,SAAQ,IAAI,CAAC,gBAAgB,EAAE,YAAY,GAAG,WAAW,CAAC;IAC9F;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,qBAAa,aAAc,SAAQ,SAAS;IAC1C,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;gBAEhB,IAAI,EAAE,oBAAoB;IAUtC,aAAa,IAAI,MAAM;CAKxB"}

package/dist/errors/auth.js

@@ -0,0 +1,19 @@
+import { HazoError } from './base.js';
+export class HazoAuthError extends HazoError {
+    forbidden;
+    constructor(opts) {
+        const { forbidden = false, ...rest } = opts;
+        super({
+            httpStatus: forbidden ? 403 : 401,
+            retryable: false,
+            ...rest,
+        });
+        this.forbidden = forbidden;
+    }
+    toUserMessage() {
+        return this.forbidden
+            ? "You don't have permission to do that."
+            : 'Authentication required.';
+    }
+}
+//# sourceMappingURL=auth.js.map

package/dist/errors/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/errors/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAyB,MAAM,WAAW,CAAC;AAU7D,MAAM,OAAO,aAAc,SAAQ,SAAS;IACjC,SAAS,CAAU;IAE5B,YAAY,IAA0B;QACpC,MAAM,EAAE,SAAS,GAAG,KAAK,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC;QAC5C,KAAK,CAAC;YACJ,UAAU,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG;YACjC,SAAS,EAAE,KAAK;YAChB,GAAG,IAAI;SACR,CAAC,CAAC;QACH,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;IAED,aAAa;QACX,OAAO,IAAI,CAAC,SAAS;YACnB,CAAC,CAAC,uCAAuC;YACzC,CAAC,CAAC,0BAA0B,CAAC;IACjC,CAAC;CACF"}

package/dist/errors/base.d.ts

@@ -0,0 +1,89 @@
+import { HAZO_ERROR_SYMBOL } from '../constants.js';
+export interface HazoErrorOptions {
+    code: string;
+    pkg: string;
+    message: string;
+    httpStatus?: number;
+    context?: Record<string, unknown>;
+    retryable?: boolean;
+    cause?: Error;
+}
+export declare class HazoError extends Error {
+    readonly code: string;
+    readonly pkg: string;
+    readonly httpStatus?: number;
+    readonly context?: Record<string, unknown>;
+    readonly correlationId?: string;
+    readonly env: string;
+    readonly retryable: boolean;
+    readonly cause?: Error;
+    /** Symbol marker used by HazoError.is() — survives realm boundaries and duplicate copies */
+    readonly [HAZO_ERROR_SYMBOL]: true;
+    constructor(opts: HazoErrorOptions);
+    /**
+     * Full serialisation of this error.
+     *
+     * Stack is included only when:
+     *   - process.env.HAZO_INCLUDE_STACK === '1', OR
+     *   - process.env.NODE_ENV !== 'production'
+     *
+     * Stack is never included in a browser context (typeof window !== 'undefined').
+     */
+    toJSON(): {
+        name: string;
+        code: string;
+        pkg: string;
+        message: string;
+        httpStatus?: number;
+        context?: Record<string, unknown>;
+        correlationId?: string;
+        env: string;
+        retryable: boolean;
+        cause?: {
+            name: string;
+            message: string;
+            stack?: string;
+        };
+        stack?: string;
+    };
+    /**
+     * Produces a safe HTTP response body.
+     * Never includes stack traces regardless of environment.
+     * httpStatus defaults to 500.
+     */
+    toHttpResponse(): {
+        status: number;
+        body: {
+            error: {
+                code: string;
+                message: string;
+                correlationId?: string;
+                context?: Record<string, unknown>;
+            };
+        };
+    };
+    /**
+     * Returns a safe, user-facing error message.
+     *
+     * Never includes stack traces, file paths, internal codes, or implementation details.
+     * Subclasses override this to provide more precise messages where the extra context
+     * is still user-safe (e.g. HazoNotFoundError can name the missing resource type).
+     *
+     * Status-based defaults:
+     *   400 → the error message (validation failures are written for users)
+     *   401/403 → permission/auth message
+     *   404 → not found
+     *   409 → conflict
+     *   429 → rate limit
+     *   503 → service unavailable
+     *   500 → unexpected error
+     *   other → generic fallback
+     */
+    toUserMessage(): string;
+    /**
+     * Type guard that checks the symbol marker.
+     * Safer than instanceof — works across realm boundaries and duplicate hazo_core copies.
+     */
+    static is(value: unknown): value is HazoError;
+}
+//# sourceMappingURL=base.d.ts.map

package/dist/errors/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/errors/base.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAIpD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAED,qBAAa,SAAU,SAAQ,KAAK;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC3C,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IAEvB,4FAA4F;IAC5F,SAAiB,CAAC,iBAAiB,CAAC,EAAE,IAAI,CAAC;gBAE/B,IAAI,EAAE,gBAAgB;IAsClC;;;;;;;;OAQG;IACH,MAAM,IAAI;QACR,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,GAAG,EAAE,MAAM,CAAC;QACZ,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAClC,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,GAAG,EAAE,MAAM,CAAC;QACZ,SAAS,EAAE,OAAO,CAAC;QACnB,KAAK,CAAC,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAC;YAAC,KAAK,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QAC1D,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB;IAsCD;;;;OAIG;IACH,cAAc,IAAI;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE;YACJ,KAAK,EAAE;gBACL,IAAI,EAAE,MAAM,CAAC;gBACb,OAAO,EAAE,MAAM,CAAC;gBAChB,aAAa,CAAC,EAAE,MAAM,CAAC;gBACvB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;aACnC,CAAC;SACH,CAAC;KACH;IAwBD;;;;;;;;;;;;;;;;OAgBG;IACH,aAAa,IAAI,MAAM;IAYvB;;;OAGG;IACH,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS;CAO9C"}

package/dist/errors/base.js

@@ -0,0 +1,152 @@
+import { HAZO_ERROR_SYMBOL } from '../constants.js';
+import { getCurrentEnv } from '../utils/env.js';
+import { registerSingleton } from '../singleton/index.js';
+export class HazoError extends Error {
+    code;
+    pkg;
+    httpStatus;
+    context;
+    correlationId;
+    env;
+    retryable;
+    cause;
+    constructor(opts) {
+        super(opts.message);
+        this.name = this.constructor.name;
+        this.code = opts.code;
+        this.pkg = opts.pkg;
+        this.httpStatus = opts.httpStatus;
+        this.context = opts.context;
+        this.retryable = opts.retryable ?? false;
+        this.cause = opts.cause;
+        this.env = getCurrentEnv();
+        // Set the symbol marker for cross-realm instanceof safety
+        this[HAZO_ERROR_SYMBOL] = true;
+        // Attempt to attach correlationId from AsyncLocalStorage context.
+        // Uses globalThis-based access to avoid circular imports — context/server.ts
+        // sets globalThis.__hazo_core_context_store__ when it initialises.
+        let cid;
+        try {
+            const store = globalThis['__hazo_core_context_store__'];
+            cid = store?.getStore?.()?.correlationId;
+        }
+        catch {
+            // ignore — context module not loaded yet
+        }
+        this.correlationId = cid;
+        // Preserve stack trace in V8
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+        // Register this class as the canonical error class (belt-and-braces for cross-realm safety)
+        registerSingleton('hazo_core:error_class', HazoError);
+    }
+    /**
+     * Full serialisation of this error.
+     *
+     * Stack is included only when:
+     *   - process.env.HAZO_INCLUDE_STACK === '1', OR
+     *   - process.env.NODE_ENV !== 'production'
+     *
+     * Stack is never included in a browser context (typeof window !== 'undefined').
+     */
+    toJSON() {
+        const includeStack = typeof window === 'undefined' &&
+            (process.env['HAZO_INCLUDE_STACK'] === '1' ||
+                getCurrentEnv() !== 'production');
+        const result = {
+            name: this.name,
+            code: this.code,
+            pkg: this.pkg,
+            message: this.message,
+            retryable: this.retryable,
+            env: this.env,
+        };
+        if (this.httpStatus !== undefined) {
+            result.httpStatus = this.httpStatus;
+        }
+        if (this.context !== undefined) {
+            result.context = this.context;
+        }
+        if (this.correlationId !== undefined) {
+            result.correlationId = this.correlationId;
+        }
+        if (this.cause !== undefined) {
+            result.cause = {
+                name: this.cause.name,
+                message: this.cause.message,
+                ...(includeStack && this.cause.stack ? { stack: this.cause.stack } : {}),
+            };
+        }
+        if (includeStack && this.stack) {
+            result.stack = this.stack;
+        }
+        return result;
+    }
+    /**
+     * Produces a safe HTTP response body.
+     * Never includes stack traces regardless of environment.
+     * httpStatus defaults to 500.
+     */
+    toHttpResponse() {
+        const error = {
+            code: this.code,
+            message: this.message,
+        };
+        if (this.correlationId !== undefined) {
+            error.correlationId = this.correlationId;
+        }
+        if (this.context !== undefined) {
+            error.context = this.context;
+        }
+        return {
+            status: this.httpStatus ?? 500,
+            body: { error },
+        };
+    }
+    /**
+     * Returns a safe, user-facing error message.
+     *
+     * Never includes stack traces, file paths, internal codes, or implementation details.
+     * Subclasses override this to provide more precise messages where the extra context
+     * is still user-safe (e.g. HazoNotFoundError can name the missing resource type).
+     *
+     * Status-based defaults:
+     *   400 → the error message (validation failures are written for users)
+     *   401/403 → permission/auth message
+     *   404 → not found
+     *   409 → conflict
+     *   429 → rate limit
+     *   503 → service unavailable
+     *   500 → unexpected error
+     *   other → generic fallback
+     */
+    toUserMessage() {
+        const status = this.httpStatus;
+        if (status === 400)
+            return this.message;
+        if (status === 401 || status === 403)
+            return "You don't have permission to do that.";
+        if (status === 404)
+            return 'The requested resource was not found.';
+        if (status === 409)
+            return 'This action conflicts with existing data.';
+        if (status === 429)
+            return 'Too many requests. Please try again later.';
+        if (status === 503)
+            return 'Service temporarily unavailable. Please try again.';
+        if (status === 500)
+            return 'An unexpected error occurred. Please try again.';
+        return 'An error occurred.';
+    }
+    /**
+     * Type guard that checks the symbol marker.
+     * Safer than instanceof — works across realm boundaries and duplicate hazo_core copies.
+     */
+    static is(value) {
+        return (typeof value === 'object' &&
+            value !== null &&
+            value[HAZO_ERROR_SYMBOL] === true);
+    }
+}
+//# sourceMappingURL=base.js.map

package/dist/errors/base.js.map

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

package/dist/errors/config.d.ts

@@ -0,0 +1,18 @@
+import { HazoError, type HazoErrorOptions } from './base.js';
+/**
+ * HazoConfigError — thrown when a package's config fails validation.
+ *
+ * httpStatus is intentionally undefined: config errors are process-exit-level failures,
+ * not HTTP errors. They should crash the process at startup, not be caught and 500'd.
+ *
+ * Code convention: HAZO_<PKG>_CONFIG_<DETAIL>
+ * Example: HAZO_AUTH_CONFIG_INVALID_SESSION_TIMEOUT
+ */
+export type HazoConfigErrorOptions = Omit<HazoErrorOptions, 'httpStatus' | 'retryable'> & {
+    httpStatus?: undefined;
+};
+export declare class HazoConfigError extends HazoError {
+    constructor(opts: HazoConfigErrorOptions);
+    toUserMessage(): string;
+}
+//# sourceMappingURL=config.d.ts.map

package/dist/errors/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/errors/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAE7D;;;;;;;;GAQG;AACH,MAAM,MAAM,sBAAsB,GAAG,IAAI,CAAC,gBAAgB,EAAE,YAAY,GAAG,WAAW,CAAC,GAAG;IACxF,UAAU,CAAC,EAAE,SAAS,CAAC;CACxB,CAAC;AAEF,qBAAa,eAAgB,SAAQ,SAAS;gBAChC,IAAI,EAAE,sBAAsB;IAQxC,aAAa,IAAI,MAAM;CAGxB"}

package/dist/errors/config.js

@@ -0,0 +1,14 @@
+import { HazoError } from './base.js';
+export class HazoConfigError extends HazoError {
+    constructor(opts) {
+        super({
+            retryable: false,
+            ...opts,
+            httpStatus: undefined,
+        });
+    }
+    toUserMessage() {
+        return 'Configuration error. Please contact support.';
+    }
+}
+//# sourceMappingURL=config.js.map

package/dist/errors/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/errors/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAyB,MAAM,WAAW,CAAC;AAe7D,MAAM,OAAO,eAAgB,SAAQ,SAAS;IAC5C,YAAY,IAA4B;QACtC,KAAK,CAAC;YACJ,SAAS,EAAE,KAAK;YAChB,GAAG,IAAI;YACP,UAAU,EAAE,SAAS;SACtB,CAAC,CAAC;IACL,CAAC;IAED,aAAa;QACX,OAAO,8CAA8C,CAAC;IACxD,CAAC;CACF"}

package/dist/errors/conflict.d.ts

@@ -0,0 +1,9 @@
+import { HazoError, type HazoErrorOptions } from './base.js';
+export type HazoConflictErrorOptions = Omit<HazoErrorOptions, 'httpStatus' | 'retryable'> & {
+    httpStatus?: number;
+};
+export declare class HazoConflictError extends HazoError {
+    constructor(opts: HazoConflictErrorOptions);
+    toUserMessage(): string;
+}
+//# sourceMappingURL=conflict.d.ts.map

package/dist/errors/conflict.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conflict.d.ts","sourceRoot":"","sources":["../../src/errors/conflict.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAE7D,MAAM,MAAM,wBAAwB,GAAG,IAAI,CAAC,gBAAgB,EAAE,YAAY,GAAG,WAAW,CAAC,GAAG;IAC1F,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,qBAAa,iBAAkB,SAAQ,SAAS;gBAClC,IAAI,EAAE,wBAAwB;IAQ1C,aAAa,IAAI,MAAM;CAGxB"}

package/dist/errors/conflict.js

@@ -0,0 +1,14 @@
+import { HazoError } from './base.js';
+export class HazoConflictError extends HazoError {
+    constructor(opts) {
+        super({
+            httpStatus: 409,
+            retryable: false,
+            ...opts,
+        });
+    }
+    toUserMessage() {
+        return 'This action conflicts with existing data. Please refresh and try again.';
+    }
+}
+//# sourceMappingURL=conflict.js.map

package/dist/errors/conflict.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conflict.js","sourceRoot":"","sources":["../../src/errors/conflict.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAyB,MAAM,WAAW,CAAC;AAM7D,MAAM,OAAO,iBAAkB,SAAQ,SAAS;IAC9C,YAAY,IAA8B;QACxC,KAAK,CAAC;YACJ,UAAU,EAAE,GAAG;YACf,SAAS,EAAE,KAAK;YAChB,GAAG,IAAI;SACR,CAAC,CAAC;IACL,CAAC;IAED,aAAa;QACX,OAAO,yEAAyE,CAAC;IACnF,CAAC;CACF"}

package/dist/errors/external.d.ts

@@ -0,0 +1,9 @@
+import { HazoError, type HazoErrorOptions } from './base.js';
+export type HazoExternalErrorOptions = Omit<HazoErrorOptions, 'httpStatus' | 'retryable'> & {
+    httpStatus?: number;
+};
+export declare class HazoExternalError extends HazoError {
+    constructor(opts: HazoExternalErrorOptions);
+    toUserMessage(): string;
+}
+//# sourceMappingURL=external.d.ts.map

package/dist/errors/external.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"external.d.ts","sourceRoot":"","sources":["../../src/errors/external.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAE7D,MAAM,MAAM,wBAAwB,GAAG,IAAI,CAAC,gBAAgB,EAAE,YAAY,GAAG,WAAW,CAAC,GAAG;IAC1F,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,qBAAa,iBAAkB,SAAQ,SAAS;gBAClC,IAAI,EAAE,wBAAwB;IAQ1C,aAAa,IAAI,MAAM;CAGxB"}

package/dist/errors/external.js

@@ -0,0 +1,14 @@
+import { HazoError } from './base.js';
+export class HazoExternalError extends HazoError {
+    constructor(opts) {
+        super({
+            httpStatus: 502,
+            retryable: true,
+            ...opts,
+        });
+    }
+    toUserMessage() {
+        return 'An external service is unavailable. Please try again.';
+    }
+}
+//# sourceMappingURL=external.js.map

package/dist/errors/external.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"external.js","sourceRoot":"","sources":["../../src/errors/external.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAyB,MAAM,WAAW,CAAC;AAM7D,MAAM,OAAO,iBAAkB,SAAQ,SAAS;IAC9C,YAAY,IAA8B;QACxC,KAAK,CAAC;YACJ,UAAU,EAAE,GAAG;YACf,SAAS,EAAE,IAAI;YACf,GAAG,IAAI;SACR,CAAC,CAAC;IACL,CAAC;IAED,aAAa;QACX,OAAO,uDAAuD,CAAC;IACjE,CAAC;CACF"}

package/dist/errors/from_zod.d.ts

@@ -0,0 +1,33 @@
+import type { ZodError } from 'zod';
+import { HazoValidationError } from './validation.js';
+import { HazoConfigError } from './config.js';
+/**
+ * Create a HazoValidationError from a ZodError.
+ * Typically used for request body / query param validation failures.
+ *
+ * @example
+ * const result = mySchema.safeParse(input);
+ * if (!result.success) {
+ *   throw fromZodValidation(result.error, { pkg: 'hazo_auth', code: 'HAZO_AUTH_INVALID_INPUT' });
+ * }
+ */
+export declare function fromZodValidation(zodError: ZodError, opts: {
+    pkg: string;
+    code: string;
+    httpStatus?: number;
+}): HazoValidationError;
+/**
+ * Create a HazoConfigError from a ZodError.
+ * Typically used when a package's INI config fails its Zod schema validation.
+ *
+ * @example
+ * const result = configSchema.safeParse(rawConfig);
+ * if (!result.success) {
+ *   throw fromZodConfig(result.error, { pkg: 'hazo_auth', code: 'HAZO_AUTH_CONFIG_INVALID' });
+ * }
+ */
+export declare function fromZodConfig(zodError: ZodError, opts: {
+    pkg: string;
+    code: string;
+}): HazoConfigError;
+//# sourceMappingURL=from_zod.d.ts.map

package/dist/errors/from_zod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"from_zod.d.ts","sourceRoot":"","sources":["../../src/errors/from_zod.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,KAAK,CAAC;AACpC,OAAO,EAAE,mBAAmB,EAAwB,MAAM,iBAAiB,CAAC;AAC5E,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAY9C;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GACvD,mBAAmB,CAiBrB;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAClC,eAAe,CAgBjB"}