hazo_core 1.0.0

package/README.md

@@ -0,0 +1,84 @@
+# hazo_core
+
+Foundation package for every `hazo_*` package — errors, correlation ID propagation, config loading, logger factory, debug factory, singleton registry, and HTTP middleware.
+
+## Install
+
+```bash
+npm install hazo_core
+```
+
+Required peer deps (ship alongside hazo_core in Wave 1):
+
+```bash
+npm install hazo_logs hazo_debug
+```
+
+## Quick start
+
+```ts
+import { createLogger, loadConfig, withContext, HazoError } from 'hazo_core';
+import { defineConfig } from 'hazo_core';
+import z from 'zod';
+
+// Logger (auto-injects correlationId + pkg)
+const log = createLogger('hazo_mypackage');
+log.info('server.started', { port: 3000 });
+
+// Config (reads hazo_mypackage_config.ini, validates with Zod)
+const config = loadConfig({
+  pkg: 'hazo_mypackage',
+  schema: defineConfig({ port: z.number().default(3000) }),
+});
+
+// Correlation ID (AsyncLocalStorage on server)
+withContext({ correlationId: 'req_abc123' }, () => {
+  log.info('request.received'); // correlationId auto-included
+});
+
+// Errors
+throw new HazoNotFoundError({ code: 'HAZO_MY_NOT_FOUND', pkg: 'hazo_mypackage', message: 'Resource missing' });
+```
+
+## Public API
+
+See `design/architecture.md §5` for the complete public API surface.
+
+### Errors
+
+```ts
+import { HazoError, HazoValidationError, HazoAuthError, HazoNotFoundError,
+  HazoConflictError, HazoRateLimitError, HazoUnavailableError,
+  HazoExternalError, HazoConfigError, HazoInternalError } from 'hazo_core/errors';
+```
+
+### Context (correlation ID)
+
+```ts
+import { withContext, getContext, getCorrelationId } from 'hazo_core/context';
+```
+
+### Config, logger, debug, singletons
+
+```ts
+import { loadConfig, defineConfig, createLogger, createDebug,
+  registerSingleton, getSingleton, generateRequestId,
+  fetchWithRequestId, createRequestIdMiddleware, REQUEST_ID_HEADER } from 'hazo_core';
+```
+
+### Browser-safe subset
+
+```ts
+import { HazoError } from 'hazo_core/errors';
+import { getCorrelationId, setBrowserCorrelationId } from 'hazo_core/context';
+import { REQUEST_ID_HEADER } from 'hazo_core/client';
+```
+
+## Configuration
+
+Copy `config/hazo_core_config.ini` to your app's config directory. See `SETUP_CHECKLIST.md` for integration steps.
+
+## See also
+
+- `design/architecture.md` — full PRD and design rationale
+- `SETUP_CHECKLIST.md` — step-by-step integration guide

package/SETUP_CHECKLIST.md

@@ -0,0 +1,114 @@
+# hazo_core — Setup Checklist
+
+Step-by-step guide for integrating `hazo_core` into a consuming app or hazo_* package.
+
+## 1. Install
+
+```bash
+npm install hazo_core hazo_logs hazo_debug
+```
+
+## 2. Copy the config template
+
+```bash
+cp node_modules/hazo_core/config/hazo_core_config.ini config/hazo_core_config.ini
+```
+
+Edit `config/hazo_core_config.ini` as needed. Key settings:
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `[log] include_stack` | `false` | Include stack traces in error JSON (set to `true` for local debug) |
+
+## 3. Wire correlation ID at every entry point
+
+**Next.js App Router** — add to `app/api/[...]/route.ts`:
+
+```ts
+import { withRequestIdRouteHandler } from 'hazo_core';
+export const GET = withRequestIdRouteHandler(async (req) => { ... });
+```
+
+**Express** — add middleware:
+
+```ts
+import { createRequestIdMiddleware } from 'hazo_core';
+app.use(createRequestIdMiddleware());
+```
+
+**Background jobs / cron** — wrap worker bootstrap:
+
+```ts
+import { withContext, generateRequestId } from 'hazo_core';
+const cid = process.env.CORRELATION_ID ?? generateRequestId();
+withContext({ correlationId: cid }, () => runWorker());
+```
+
+## 4. Use the logger
+
+```ts
+import { createLogger } from 'hazo_core';
+const log = createLogger('myapp');
+log.info('server.started', { port: 3000 });
+// Logs include: pkg, correlationId, userId (if in context), env, timestamp
+```
+
+## 5. Use the config loader
+
+```ts
+import { loadConfig, defineConfig } from 'hazo_core';
+import z from 'zod';
+
+const config = loadConfig({
+  pkg: 'myapp',
+  configDir: path.join(process.cwd(), 'config'),
+  schema: defineConfig({
+    port: z.number().default(3000),
+    secret: z.string(),
+  }),
+});
+```
+
+## 6. Browser context (React apps)
+
+Wrap your React tree in `HazoContextProvider` (from `hazo_ui`):
+
+```tsx
+import { HazoContextProvider } from 'hazo_ui';
+export default function RootLayout({ children }) {
+  return <HazoContextProvider>{children}</HazoContextProvider>;
+}
+```
+
+## 7. HAZO_ENV convention
+
+Set `HAZO_ENV` in your deployment environment to declare which environment is running. Falls back to `NODE_ENV` then `'development'`.
+
+```bash
+HAZO_ENV=production node server.js
+```
+
+Create per-env config overlays:
+```
+config/hazo_core_config.ini           # base
+config/hazo_core_config.production.ini  # production overrides
+config/hazo_core_config.staging.ini     # staging overrides
+```
+
+## 8. Error handling
+
+All `hazo_*` packages throw `HazoError` subclasses. Catch at API boundaries:
+
+```ts
+import { HazoError } from 'hazo_core/errors';
+
+try {
+  await doSomething();
+} catch (err) {
+  if (HazoError.is(err)) {
+    const { status, body } = err.toHttpResponse();
+    return Response.json(body, { status });
+  }
+  throw err;
+}
+```

package/config/hazo_core_config.ini

@@ -0,0 +1,14 @@
+; hazo_core configuration
+; All values can be overridden via env vars: HAZO_CORE_<SECTION>_<KEY>=value
+
+[log]
+; Include stack traces in HazoError.toJSON() and log output.
+; Default: false in production, true otherwise.
+; Override with HAZO_INCLUDE_STACK=1 to force on.
+include_stack = false
+
+[env]
+; This section is an example of the per-env overlay convention.
+; Create hazo_core_config.<env>.ini alongside this file to override values
+; for a specific HAZO_ENV (e.g. hazo_core_config.development.ini).
+; See hazo_core/SETUP_CHECKLIST.md for details.

package/dist/config/index.d.ts

@@ -0,0 +1,35 @@
+import type { ZodSchema, ZodRawShape } from 'zod';
+import { z } from 'zod';
+interface LoadConfigOptions<T> {
+    /** Package name e.g. 'hazo_auth' — used to build filename and env-var prefix */
+    pkg: string;
+    /** Defaults to process.cwd()/config */
+    configDir?: string;
+    /** Zod schema to validate the merged config object */
+    schema: ZodSchema<T>;
+    /** Defaults to getCurrentEnv() */
+    env?: string;
+}
+/**
+ * Load, merge, validate, and cache a package config.
+ *
+ * Load order (per §8 + D-003 + D-020 hook 2):
+ *   1. <configDir>/hazo_<pkg>_config.ini                (base)
+ *   2. <configDir>/hazo_<pkg>_config.<env>.ini          (env overlay, skipped when env is 'development')
+ *   3. HAZO_<PKG>_<SECTION>_<KEY> env-var overrides
+ *   4. Zod validation — throws HazoConfigError on failure
+ *   5. Cache under `${pkg}:${resolvedEnv}`
+ */
+export declare function loadConfig<T>(opts: LoadConfigOptions<T>): T;
+/**
+ * Invalidate the config cache for a given package (all envs).
+ * Primarily for tests and the hazo_debug "reload config" UI button.
+ */
+export declare function reloadConfig(pkg: string): void;
+/**
+ * Thin wrapper around z.object() that documents intent.
+ * Each package keeps its schema in src/config/schema.ts.
+ */
+export declare function defineConfig<T extends ZodRawShape>(shape: T): z.ZodObject<T>;
+export {};
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,KAAK,CAAC;AAClD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB,UAAU,iBAAiB,CAAC,CAAC;IAC3B,gFAAgF;IAChF,GAAG,EAAE,MAAM,CAAC;IACZ,uCAAuC;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC;IACrB,kCAAkC;IAClC,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAqED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,IAAI,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,CAAC,CAoC3D;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAM9C;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,WAAW,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAE5E"}

package/dist/config/index.js

@@ -0,0 +1,117 @@
+import { z } from 'zod';
+import * as path from 'node:path';
+import { parseIniFile, mergeIni } from './ini_parser.js';
+import { fromZodConfig } from '../errors/from_zod.js';
+import { getCurrentEnv } from '../utils/env.js';
+// Cache: `${pkg}:${env}` → parsed + validated config
+const configCache = new Map();
+/**
+ * Normalize a package name to the UPPER_SNAKE form used in env-var prefixes.
+ * e.g. 'hazo_llm_api' → 'HAZO_LLM_API'
+ */
+function pkgToEnvPrefix(pkg) {
+    return pkg.toUpperCase();
+}
+/**
+ * Apply env-var overrides to a merged INI object.
+ *
+ * Scans process.env for keys matching HAZO_<PKG>_<SECTION>_<KEY> and writes
+ * them into the merged object at [section][key] (lowercase).
+ *
+ * Per D-003 and D-020 hook 6.
+ */
+function applyEnvVarOverrides(merged, pkg) {
+    const prefix = `${pkgToEnvPrefix(pkg)}_`;
+    const result = { ...merged };
+    const overrideKeys = [];
+    for (const [envKey, envValue] of Object.entries(process.env)) {
+        if (envValue === undefined)
+            continue;
+        if (!envKey.startsWith(prefix))
+            continue;
+        // Strip the prefix and split remaining into [SECTION, KEY]
+        const remainder = envKey.slice(prefix.length);
+        const parts = remainder.split('_');
+        if (parts.length < 2) {
+            // Must have at least SECTION_KEY
+            continue;
+        }
+        // Convention: everything except the last token is the section,
+        // and the last token is the key. This handles multi-word sections/keys
+        // that are already joined with underscores in the env-var name.
+        // Simple heuristic: first token is section, rest joined as key.
+        const sectionUpper = parts[0];
+        const keyUpper = parts.slice(1).join('_');
+        const section = sectionUpper.toLowerCase();
+        const key = keyUpper.toLowerCase();
+        // Ensure section exists
+        if (typeof result[section] !== 'object' || result[section] === null) {
+            result[section] = {};
+        }
+        result[section][key] = envValue;
+        overrideKeys.push(`${section}.${key}`);
+    }
+    if (overrideKeys.length > 0) {
+        console.info(`[hazo_core/loadConfig] ${pkg}: env-var overrides applied for: ${overrideKeys.join(', ')}`);
+    }
+    return result;
+}
+/**
+ * Load, merge, validate, and cache a package config.
+ *
+ * Load order (per §8 + D-003 + D-020 hook 2):
+ *   1. <configDir>/hazo_<pkg>_config.ini                (base)
+ *   2. <configDir>/hazo_<pkg>_config.<env>.ini          (env overlay, skipped when env is 'development')
+ *   3. HAZO_<PKG>_<SECTION>_<KEY> env-var overrides
+ *   4. Zod validation — throws HazoConfigError on failure
+ *   5. Cache under `${pkg}:${resolvedEnv}`
+ */
+export function loadConfig(opts) {
+    const resolvedEnv = opts.env ?? getCurrentEnv();
+    const cacheKey = `${opts.pkg}:${resolvedEnv}`;
+    if (configCache.has(cacheKey)) {
+        return configCache.get(cacheKey);
+    }
+    const configDir = opts.configDir ?? path.join(process.cwd(), 'config');
+    // 1. Base INI
+    const baseFile = path.join(configDir, `hazo_${opts.pkg}_config.ini`);
+    let merged = parseIniFile(baseFile);
+    // 2. Env overlay (skip for development)
+    if (resolvedEnv !== 'development') {
+        const overlayFile = path.join(configDir, `hazo_${opts.pkg}_config.${resolvedEnv}.ini`);
+        const overlay = parseIniFile(overlayFile);
+        merged = mergeIni(merged, overlay);
+    }
+    // 3. Env-var overrides
+    merged = applyEnvVarOverrides(merged, opts.pkg);
+    // 4. Zod validation
+    const result = opts.schema.safeParse(merged);
+    if (!result.success) {
+        throw fromZodConfig(result.error, {
+            pkg: opts.pkg,
+            code: `HAZO_${opts.pkg.toUpperCase()}_CONFIG_INVALID`,
+        });
+    }
+    // 5. Cache and return
+    configCache.set(cacheKey, result.data);
+    return result.data;
+}
+/**
+ * Invalidate the config cache for a given package (all envs).
+ * Primarily for tests and the hazo_debug "reload config" UI button.
+ */
+export function reloadConfig(pkg) {
+    for (const key of Array.from(configCache.keys())) {
+        if (key.startsWith(`${pkg}:`)) {
+            configCache.delete(key);
+        }
+    }
+}
+/**
+ * Thin wrapper around z.object() that documents intent.
+ * Each package keeps its schema in src/config/schema.ts.
+ */
+export function defineConfig(shape) {
+    return z.object(shape);
+}
+//# sourceMappingURL=index.js.map

package/dist/config/index.js.map

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

package/dist/config/ini_parser.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Read and parse an INI file. Returns an empty object if file not found.
+ */
+export declare function parseIniFile(filePath: string): Record<string, unknown>;
+/**
+ * Merge two parsed INI objects. Overlay values win for scalar conflicts;
+ * nested objects are shallow-merged.
+ */
+export declare function mergeIni(base: Record<string, unknown>, overlay: Record<string, unknown>): Record<string, unknown>;
+//# sourceMappingURL=ini_parser.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ini_parser.d.ts","sourceRoot":"","sources":["../../src/config/ini_parser.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAUtE;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CACtB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAyBzB"}

package/dist/config/ini_parser.js

@@ -0,0 +1,45 @@
+import { parse } from 'ini';
+import { readFileSync, existsSync } from 'node:fs';
+/**
+ * Read and parse an INI file. Returns an empty object if file not found.
+ */
+export function parseIniFile(filePath) {
+    if (!existsSync(filePath)) {
+        return {};
+    }
+    try {
+        const content = readFileSync(filePath, 'utf-8');
+        return parse(content);
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Merge two parsed INI objects. Overlay values win for scalar conflicts;
+ * nested objects are shallow-merged.
+ */
+export function mergeIni(base, overlay) {
+    const result = { ...base };
+    for (const [key, value] of Object.entries(overlay)) {
+        const baseValue = result[key];
+        if (value !== null &&
+            typeof value === 'object' &&
+            !Array.isArray(value) &&
+            baseValue !== null &&
+            typeof baseValue === 'object' &&
+            !Array.isArray(baseValue)) {
+            // Both sides are plain objects — shallow-merge
+            result[key] = {
+                ...baseValue,
+                ...value,
+            };
+        }
+        else {
+            // Overlay wins
+            result[key] = value;
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=ini_parser.js.map

package/dist/config/ini_parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ini_parser.js","sourceRoot":"","sources":["../../src/config/ini_parser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,KAAK,CAAC;AAC5B,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAEnD;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,QAAgB;IAC3C,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC1B,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAChD,OAAO,KAAK,CAAC,OAAO,CAA4B,CAAC;IACnD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,QAAQ,CACtB,IAA6B,EAC7B,OAAgC;IAEhC,MAAM,MAAM,GAA4B,EAAE,GAAG,IAAI,EAAE,CAAC;IAEpD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACnD,MAAM,SAAS,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QAC9B,IACE,KAAK,KAAK,IAAI;YACd,OAAO,KAAK,KAAK,QAAQ;YACzB,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;YACrB,SAAS,KAAK,IAAI;YAClB,OAAO,SAAS,KAAK,QAAQ;YAC7B,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,EACzB,CAAC;YACD,+CAA+C;YAC/C,MAAM,CAAC,GAAG,CAAC,GAAG;gBACZ,GAAI,SAAqC;gBACzC,GAAI,KAAiC;aACtC,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,eAAe;YACf,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACtB,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/constants.d.ts

@@ -0,0 +1,4 @@
+export declare const REQUEST_ID_HEADER = "x-request-id";
+export declare const HAZO_ERROR_SYMBOL: unique symbol;
+export declare const HAZO_SINGLETONS_KEY = "__hazo_core_singletons__";
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,iBAAiB,iBAAiB,CAAC;AAChD,eAAO,MAAM,iBAAiB,eAAgC,CAAC;AAC/D,eAAO,MAAM,mBAAmB,6BAA6B,CAAC"}

package/dist/constants.js

@@ -0,0 +1,4 @@
+export const REQUEST_ID_HEADER = 'x-request-id';
+export const HAZO_ERROR_SYMBOL = Symbol.for('hazo_core:error');
+export const HAZO_SINGLETONS_KEY = '__hazo_core_singletons__';
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,iBAAiB,GAAG,cAAc,CAAC;AAChD,MAAM,CAAC,MAAM,iBAAiB,GAAG,MAAM,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;AAC/D,MAAM,CAAC,MAAM,mBAAmB,GAAG,0BAA0B,CAAC"}

package/dist/context/client.d.ts

@@ -0,0 +1,27 @@
+import type { HazoContext } from './types.js';
+/**
+ * Set (or clear) the browser-side correlation ID.
+ * Pass undefined to clear the current context.
+ * Typically called by hazo_ui's <HazoContextProvider> on mount.
+ */
+export declare function setBrowserCorrelationId(id?: string): void;
+/**
+ * Read the current browser context.
+ * Returns undefined when no context has been set.
+ */
+export declare function getContext(): HazoContext | undefined;
+/**
+ * Convenience accessor for the correlation ID.
+ * Returns undefined when no context has been set.
+ */
+export declare function getCorrelationId(): string | undefined;
+/**
+ * Synchronously run `fn` within a new context derived from `values`.
+ * Saves and restores the previous context so calls can be nested.
+ *
+ * Unlike the server implementation, this is synchronous-only — there is no
+ * async boundary tracking. Concurrent async operations in a browser will share
+ * the same context ref, which is appropriate for the single-tab model.
+ */
+export declare function withContext<T>(values: Partial<HazoContext>, fn: () => T): T;
+//# sourceMappingURL=client.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/context/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAc9C;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CASzD;AAED;;;GAGG;AACH,wBAAgB,UAAU,IAAI,WAAW,GAAG,SAAS,CAEpD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,GAAG,SAAS,CAErD;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,WAAW,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAmB3E"}

package/dist/context/client.js

@@ -0,0 +1,66 @@
+/**
+ * Browser context implementation — single mutable ref per tab.
+ *
+ * The server's AsyncLocalStorage is not available in browsers. A single module-level
+ * ref matches the one-tab-one-context reality (per D-004).
+ *
+ * In React apps, hazo_ui's <HazoContextProvider> calls setBrowserCorrelationId() on
+ * mount so all downstream code (fetch wrappers, error constructors) can read the ID.
+ */
+let _currentContext;
+/**
+ * Set (or clear) the browser-side correlation ID.
+ * Pass undefined to clear the current context.
+ * Typically called by hazo_ui's <HazoContextProvider> on mount.
+ */
+export function setBrowserCorrelationId(id) {
+    if (id === undefined) {
+        _currentContext = undefined;
+    }
+    else {
+        _currentContext = {
+            ..._currentContext,
+            correlationId: id,
+        };
+    }
+}
+/**
+ * Read the current browser context.
+ * Returns undefined when no context has been set.
+ */
+export function getContext() {
+    return _currentContext;
+}
+/**
+ * Convenience accessor for the correlation ID.
+ * Returns undefined when no context has been set.
+ */
+export function getCorrelationId() {
+    return _currentContext?.correlationId;
+}
+/**
+ * Synchronously run `fn` within a new context derived from `values`.
+ * Saves and restores the previous context so calls can be nested.
+ *
+ * Unlike the server implementation, this is synchronous-only — there is no
+ * async boundary tracking. Concurrent async operations in a browser will share
+ * the same context ref, which is appropriate for the single-tab model.
+ */
+export function withContext(values, fn) {
+    const previous = _currentContext;
+    const merged = values.correlationId !== undefined || previous !== undefined
+        ? {
+            ...previous,
+            ...values,
+            correlationId: values.correlationId ?? previous?.correlationId ?? '',
+        }
+        : undefined;
+    _currentContext = merged;
+    try {
+        return fn();
+    }
+    finally {
+        _currentContext = previous;
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/context/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/context/client.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AAEH,IAAI,eAAwC,CAAC;AAE7C;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CAAC,EAAW;IACjD,IAAI,EAAE,KAAK,SAAS,EAAE,CAAC;QACrB,eAAe,GAAG,SAAS,CAAC;IAC9B,CAAC;SAAM,CAAC;QACN,eAAe,GAAG;YAChB,GAAG,eAAe;YAClB,aAAa,EAAE,EAAE;SAClB,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU;IACxB,OAAO,eAAe,CAAC;AACzB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB;IAC9B,OAAO,eAAe,EAAE,aAAa,CAAC;AACxC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAI,MAA4B,EAAE,EAAW;IACtE,MAAM,QAAQ,GAAG,eAAe,CAAC;IAEjC,MAAM,MAAM,GACV,MAAM,CAAC,aAAa,KAAK,SAAS,IAAI,QAAQ,KAAK,SAAS;QAC1D,CAAC,CAAC;YACE,GAAG,QAAQ;YACX,GAAG,MAAM;YACT,aAAa,EAAE,MAAM,CAAC,aAAa,IAAI,QAAQ,EAAE,aAAa,IAAI,EAAE;SACrE;QACH,CAAC,CAAC,SAAS,CAAC;IAEhB,eAAe,GAAG,MAAM,CAAC;IAEzB,IAAI,CAAC;QACH,OAAO,EAAE,EAAE,CAAC;IACd,CAAC;YAAS,CAAC;QACT,eAAe,GAAG,QAAQ,CAAC;IAC7B,CAAC;AACH,CAAC"}

package/dist/context/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Server-side context implementation (AsyncLocalStorage).
+ *
+ * Browser-safe consumers should import from 'hazo_core/client' or directly from
+ * './client.js' — they cannot use this file as it imports node:async_hooks.
+ */
+export { withContext, getContext, getCorrelationId } from './server.js';
+export type { HazoContext } from './types.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/context/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACxE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC"}

package/dist/context/index.js

@@ -0,0 +1,8 @@
+/**
+ * Server-side context implementation (AsyncLocalStorage).
+ *
+ * Browser-safe consumers should import from 'hazo_core/client' or directly from
+ * './client.js' — they cannot use this file as it imports node:async_hooks.
+ */
+export { withContext, getContext, getCorrelationId } from './server.js';
+//# sourceMappingURL=index.js.map

package/dist/context/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/context/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC"}

package/dist/context/server.d.ts

@@ -0,0 +1,23 @@
+import type { HazoContext } from './types.js';
+/**
+ * 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 declare function withContext<T>(values: Partial<HazoContext>, fn: () => T): T;
+/**
+ * Read the current context, if any.
+ * Returns undefined when called outside a withContext() scope.
+ */
+export declare function getContext(): HazoContext | undefined;
+/**
+ * Convenience accessor for the most-commonly-needed context field.
+ * Returns undefined when called outside a withContext() scope.
+ */
+export declare function getCorrelationId(): string | undefined;
+//# sourceMappingURL=server.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/context/server.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAkB9C;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,WAAW,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAc3E;AAED;;;GAGG;AACH,wBAAgB,UAAU,IAAI,WAAW,GAAG,SAAS,CAEpD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,GAAG,SAAS,CAErD"}