@couimet/execution-context 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Charles Ouimet
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,138 @@
+# @couimet/execution-context
+
+[![npm version](https://img.shields.io/npm/v/@couimet/execution-context.svg?style=flat-square)](https://www.npmjs.com/package/@couimet/execution-context) [![Coverage](https://codecov.io/gh/couimet/ts-npm-packages/branch/main/graph/badge.svg?flag=execution-context)](https://codecov.io/gh/couimet/ts-npm-packages?flag=execution-context) [![npm downloads](https://img.shields.io/npm/dm/@couimet/execution-context.svg?style=flat-square)](https://www.npmjs.com/package/@couimet/execution-context)
+
+`ExecutionContext.run()` opens a scope that carries a correlation id, a request id, and an attribute bag. Code inside the scope, including work resumed after `await`, reads the same ids and attributes. The scope follows OpenTelemetry's context propagation, which `AsyncLocalStorage` carries across async boundaries. `run()` pins a provided id and generates a fresh one when a field is `undefined` or blank. Typical priming sites are an application bootstrap, a middleware that scopes one HTTP request, and a timer that scopes one scheduled run.
+
+## Install
+
+```bash
+pnpm add @couimet/execution-context
+```
+
+The package declares `@opentelemetry/api` and `@couimet/detailed-error` as peer dependencies, and pnpm or npm installs them automatically. The `AsyncLocalStorage` context manager that `run()` relies on ships as the direct dependency `@opentelemetry/context-async-hooks`.
+
+## Usage
+
+```typescript
+import { CorrelationId, ExecutionContext } from '@couimet/execution-context';
+
+ExecutionContext.run({ correlationId: 'my-job', requestId: 'abc-123', attributes: { userId: 'u-42' } }, () => {
+  const id = ExecutionContext.correlationId.toString(); // 'my-job'
+  ExecutionContext.addAttributes({ attempt: 2 });
+  // awaited work below still reads this scope
+});
+
+ExecutionContext.isActive(); // false, once the run has returned
+```
+
+Pass an id to pin it. Pass `undefined` or a blank string, and `run()` generates a fresh one through `fromStringOrCreate()`. An explicit blank passed to `fromString()` throws instead. A nested `run()` starts a fresh scope, so it does not inherit the outer ids unless the caller passes them in.
+
+## How it works
+
+A `run()` executes its callback inside a new OpenTelemetry context. It first builds a store that holds a `CorrelationId`, a `RequestId`, and an attribute bag. Then it installs that store on the active context and runs the callback. When the callback returns or throws, the previous context is restored. Sibling `run()` calls therefore never see each other's values.
+
+The callback may be sync or async. `run` returns whatever the callback returns. An async callback's awaited work still reads the same context, because `AsyncLocalStorage` propagates the context through the async chain. One request id can therefore follow a log line emitted deep inside an awaited service call.
+
+The package installs the OpenTelemetry global context manager exactly once. The first `run()` performs the install lazily. Callers that never `run` can still install the manager up front with `ensureContextManagerInitialized()`. The global manager can be set only once, and another component may already own the slot. When it does, `run()` and `ensureContextManagerInitialized()` throw a `DetailedError` with code `CONTEXT_MANAGER_REGISTRATION_FAILED` rather than propagate ids through a manager this package cannot verify.
+
+## API reference
+
+The barrel re-exports four modules: `ExecutionContext`, the `CorrelationId` and `RequestId` value objects, and the `ExecutionContextErrorCodes` enum.
+
+### CorrelationId
+
+An opaque value object that wraps a correlation id string. The wrapped value is private, so `toString()` is the only way to read it. Compare two ids through their `toString()` results, not by reference.
+
+```typescript
+class CorrelationId {
+  static create(): CorrelationId;
+  static fromString(value: string): CorrelationId;
+  static fromStringOrCreate(value: string | undefined): CorrelationId;
+  toString(): string;
+}
+```
+
+- `create()` returns a fresh id from a UUID v4.
+- `fromString(value)` wraps `value` when it is non-blank. Otherwise it throws a `DetailedError` with code `INVALID_BLANK_CORRELATION_ID`, message `correlationId must be a non-blank string`, and `functionName` `CorrelationId.fromString`. The `details` carry the offending value. A non-primitive value is rejected by the shared string guard with code `INVALID_STRING_TYPE`.
+- `fromStringOrCreate(value)` never throws for a primitive string or `undefined`. A non-blank value is pinned through `fromString`, a blank or missing value falls back to `create()`, and a non-primitive value is rejected by the shared string guard with code `INVALID_STRING_TYPE`.
+- `toString()` returns the wrapped string.
+
+### ExecutionContext
+
+A static-only runner whose constructor is private. Every member reads or writes the store active on the current OpenTelemetry context.
+
+```typescript
+type ContextAttributes = Record<string, unknown>;
+
+interface RunParams {
+  readonly correlationId: string | undefined;
+  readonly requestId: string | undefined;
+  readonly attributes?: ContextAttributes;
+}
+
+class ExecutionContext {
+  static ensureContextManagerInitialized(): void;
+  static run<T>(data: RunParams, fn: () => T): T;
+  static isActive(): boolean;
+  static get correlationId(): CorrelationId;
+  static get requestId(): RequestId;
+  static getAttribute(key: string): unknown;
+  static addAttributes(attrs: ContextAttributes): void;
+  static getAttributes(): ContextAttributes;
+}
+```
+
+- `ensureContextManagerInitialized()` installs the OpenTelemetry `AsyncLocalStorage` context manager as the global manager. It is idempotent, so a second call is a no-op. `run()` calls it automatically on first use. It throws a `DetailedError` with code `CONTEXT_MANAGER_REGISTRATION_FAILED` when another component already owns the global manager slot.
+- `run<T>(data, fn)` primes a fresh store and runs `fn` inside that context. Both ids go through `fromStringOrCreate`, and attributes default to `{}`. Attributes that are null, an array, or not an object throw a `DetailedError` with code `INVALID_CONTEXT_ATTRIBUTES`. It returns whatever `fn` returns. Anything previously active is replaced for the duration of `fn`, then restored when `fn` returns or throws.
+- `isActive()` returns true when the current code is executing inside a `run` block.
+- The `correlationId` and `requestId` getters return the primed id. Called outside a run, they throw a `DetailedError` with code `NO_ACTIVE_CONTEXT`.
+- `getAttribute(key)` returns the stored attribute for `key`, or `undefined` when the key is absent or no scope is active.
+- `addAttributes(attrs)` merges `attrs` into the active attribute bag, with later keys winning. Attributes that are null, an array, or not an object throw a `DetailedError` with code `INVALID_CONTEXT_ATTRIBUTES` before the merge. It replaces the bag object, so a reference captured earlier does not see the merge. It is a no-op when no scope is active.
+- `getAttributes()` returns the active attribute bag, which is the live bag rather than a copy. It returns `{}` when no scope is active.
+
+### ExecutionContextErrorCodes
+
+Error codes used by the `DetailedError` instances that this package throws:
+
+```typescript
+enum ExecutionContextErrorCodes {
+  INVALID_BLANK_CORRELATION_ID = 'INVALID_BLANK_CORRELATION_ID',
+  INVALID_BLANK_REQUEST_ID = 'INVALID_BLANK_REQUEST_ID',
+  NO_ACTIVE_CONTEXT = 'NO_ACTIVE_CONTEXT',
+  CONTEXT_MANAGER_REGISTRATION_FAILED = 'CONTEXT_MANAGER_REGISTRATION_FAILED',
+  INVALID_CONTEXT_ATTRIBUTES = 'INVALID_CONTEXT_ATTRIBUTES',
+  INVALID_STRING_TYPE = 'INVALID_STRING_TYPE',
+}
+```
+
+`fromString` on either id throws `INVALID_BLANK_CORRELATION_ID` or `INVALID_BLANK_REQUEST_ID`. The two getters throw `NO_ACTIVE_CONTEXT`. `ensureContextManagerInitialized()` throws `CONTEXT_MANAGER_REGISTRATION_FAILED` when another component already owns the global context manager slot. `run()` and `addAttributes()` throw `INVALID_CONTEXT_ATTRIBUTES` when attributes are null, an array, or not an object. `fromString` and `fromStringOrCreate` on either id throw `INVALID_STRING_TYPE` when the value is not a primitive string, such as a boxed `String`. Every error is a `DetailedError` from [`@couimet/detailed-error`](https://github.com/couimet/ts-npm-packages/tree/main/packages/detailed-error).
+
+### RequestId
+
+Identical in shape to `CorrelationId`, holding a request id string:
+
+```typescript
+class RequestId {
+  static create(): RequestId;
+  static fromString(value: string): RequestId;
+  static fromStringOrCreate(value: string | undefined): RequestId;
+  toString(): string;
+}
+```
+
+The behavior matches `CorrelationId`, with `INVALID_BLANK_REQUEST_ID` thrown by `fromString` on a blank value and `INVALID_STRING_TYPE` thrown when the value is not a primitive string.
+
+## Package family
+
+`@couimet/execution-context` holds only the scope machinery. It ships the `ExecutionContext` runner, the `CorrelationId` and `RequestId` value objects, the attribute-bag types, and `ExecutionContextErrorCodes`. It carries no knowledge of HTTP or of any framework.
+
+Companion packages group the transport and framework concerns, and each carries its integration in the package name. One companion exists today:
+
+- `@couimet/execution-context-http` exports the wire header names (`x-correlation-id`, `x-request-id`) as the `HttpHeaders` enum. It has no framework dependency.
+
+Future framework adapters follow the same shape. The adapter reads the two header names from `@couimet/execution-context-http`, pulls the ids off an incoming request, and calls `ExecutionContext.run()` with them. Each adapter lives in its own package, such as `@couimet/execution-context-http-middy` or `@couimet/execution-context-http-koa`. The core package never depends on a framework.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,62 @@
+declare class CorrelationId {
+    private readonly value;
+    private constructor();
+    static create(): CorrelationId;
+    static fromString(value: string): CorrelationId;
+    /** Never throws for a primitive string or undefined: blank or missing values fall back to a generated id. */
+    static fromStringOrCreate(value: string | undefined): CorrelationId;
+    toString(): string;
+}
+
+declare class RequestId {
+    private readonly value;
+    private constructor();
+    static create(): RequestId;
+    static fromString(value: string): RequestId;
+    /** Never throws for a primitive string or undefined: blank or missing values fall back to a generated id. */
+    static fromStringOrCreate(value: string | undefined): RequestId;
+    toString(): string;
+}
+
+type ContextAttributes = Record<string, unknown>;
+interface RunParams {
+    readonly correlationId: string | undefined;
+    readonly requestId: string | undefined;
+    readonly attributes?: ContextAttributes;
+}
+declare class ExecutionContext {
+    private static contextInitialized;
+    private constructor();
+    /**
+     * Installs the global context manager exactly once. Idempotent: later calls
+     * are a no-op once installed. Throws when another component already owns the
+     * global manager slot, because the package then cannot guarantee that async
+     * work inherits the primed ids and failing loud beats silent loss of ids.
+     */
+    static ensureContextManagerInitialized(): void;
+    private static getStore;
+    /**
+     * Primes the execution context; anything previously set gets wiped.
+     * Call sites are the app bootstrap, middleware priming the context from a
+     * request, and timer runs scoping a single execution.
+     */
+    static run<T>(data: RunParams, fn: () => T): T;
+    static isActive(): boolean;
+    private static requireStore;
+    static get correlationId(): CorrelationId;
+    static get requestId(): RequestId;
+    static getAttribute(key: string): unknown;
+    static addAttributes(attrs: ContextAttributes): void;
+    static getAttributes(): ContextAttributes;
+}
+
+declare enum ExecutionContextErrorCodes {
+    INVALID_BLANK_CORRELATION_ID = "INVALID_BLANK_CORRELATION_ID",
+    INVALID_BLANK_REQUEST_ID = "INVALID_BLANK_REQUEST_ID",
+    INVALID_CONTEXT_ATTRIBUTES = "INVALID_CONTEXT_ATTRIBUTES",
+    INVALID_STRING_TYPE = "INVALID_STRING_TYPE",
+    NO_ACTIVE_CONTEXT = "NO_ACTIVE_CONTEXT",
+    CONTEXT_MANAGER_REGISTRATION_FAILED = "CONTEXT_MANAGER_REGISTRATION_FAILED"
+}
+
+export { type ContextAttributes, CorrelationId, ExecutionContext, ExecutionContextErrorCodes, RequestId, type RunParams };

package/dist/index.d.ts

@@ -0,0 +1,62 @@
+declare class CorrelationId {
+    private readonly value;
+    private constructor();
+    static create(): CorrelationId;
+    static fromString(value: string): CorrelationId;
+    /** Never throws for a primitive string or undefined: blank or missing values fall back to a generated id. */
+    static fromStringOrCreate(value: string | undefined): CorrelationId;
+    toString(): string;
+}
+
+declare class RequestId {
+    private readonly value;
+    private constructor();
+    static create(): RequestId;
+    static fromString(value: string): RequestId;
+    /** Never throws for a primitive string or undefined: blank or missing values fall back to a generated id. */
+    static fromStringOrCreate(value: string | undefined): RequestId;
+    toString(): string;
+}
+
+type ContextAttributes = Record<string, unknown>;
+interface RunParams {
+    readonly correlationId: string | undefined;
+    readonly requestId: string | undefined;
+    readonly attributes?: ContextAttributes;
+}
+declare class ExecutionContext {
+    private static contextInitialized;
+    private constructor();
+    /**
+     * Installs the global context manager exactly once. Idempotent: later calls
+     * are a no-op once installed. Throws when another component already owns the
+     * global manager slot, because the package then cannot guarantee that async
+     * work inherits the primed ids and failing loud beats silent loss of ids.
+     */
+    static ensureContextManagerInitialized(): void;
+    private static getStore;
+    /**
+     * Primes the execution context; anything previously set gets wiped.
+     * Call sites are the app bootstrap, middleware priming the context from a
+     * request, and timer runs scoping a single execution.
+     */
+    static run<T>(data: RunParams, fn: () => T): T;
+    static isActive(): boolean;
+    private static requireStore;
+    static get correlationId(): CorrelationId;
+    static get requestId(): RequestId;
+    static getAttribute(key: string): unknown;
+    static addAttributes(attrs: ContextAttributes): void;
+    static getAttributes(): ContextAttributes;
+}
+
+declare enum ExecutionContextErrorCodes {
+    INVALID_BLANK_CORRELATION_ID = "INVALID_BLANK_CORRELATION_ID",
+    INVALID_BLANK_REQUEST_ID = "INVALID_BLANK_REQUEST_ID",
+    INVALID_CONTEXT_ATTRIBUTES = "INVALID_CONTEXT_ATTRIBUTES",
+    INVALID_STRING_TYPE = "INVALID_STRING_TYPE",
+    NO_ACTIVE_CONTEXT = "NO_ACTIVE_CONTEXT",
+    CONTEXT_MANAGER_REGISTRATION_FAILED = "CONTEXT_MANAGER_REGISTRATION_FAILED"
+}
+
+export { type ContextAttributes, CorrelationId, ExecutionContext, ExecutionContextErrorCodes, RequestId, type RunParams };

package/dist/index.js

@@ -0,0 +1,281 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  CorrelationId: () => CorrelationId,
+  ExecutionContext: () => ExecutionContext,
+  ExecutionContextErrorCodes: () => ExecutionContextErrorCodes,
+  RequestId: () => RequestId
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/executionContextErrorCodes.ts
+var ExecutionContextErrorCodes = /* @__PURE__ */ ((ExecutionContextErrorCodes2) => {
+  ExecutionContextErrorCodes2["INVALID_BLANK_CORRELATION_ID"] = "INVALID_BLANK_CORRELATION_ID";
+  ExecutionContextErrorCodes2["INVALID_BLANK_REQUEST_ID"] = "INVALID_BLANK_REQUEST_ID";
+  ExecutionContextErrorCodes2["INVALID_CONTEXT_ATTRIBUTES"] = "INVALID_CONTEXT_ATTRIBUTES";
+  ExecutionContextErrorCodes2["INVALID_STRING_TYPE"] = "INVALID_STRING_TYPE";
+  ExecutionContextErrorCodes2["NO_ACTIVE_CONTEXT"] = "NO_ACTIVE_CONTEXT";
+  ExecutionContextErrorCodes2["CONTEXT_MANAGER_REGISTRATION_FAILED"] = "CONTEXT_MANAGER_REGISTRATION_FAILED";
+  return ExecutionContextErrorCodes2;
+})(ExecutionContextErrorCodes || {});
+
+// src/isNonBlank.ts
+var import_detailed_error = require("@couimet/detailed-error");
+var isNonBlank = (value) => {
+  if (value === void 0) {
+    return false;
+  }
+  if (typeof value !== "string") {
+    throw new import_detailed_error.DetailedError({
+      code: "INVALID_STRING_TYPE" /* INVALID_STRING_TYPE */,
+      message: "expected a primitive string or undefined",
+      functionName: "isNonBlank",
+      details: {}
+    });
+  }
+  return value.trim() !== "";
+};
+
+// src/correlationId.ts
+var import_detailed_error2 = require("@couimet/detailed-error");
+
+// ../../node_modules/.pnpm/uuid@14.0.1/node_modules/uuid/dist-node/stringify.js
+var byteToHex = [];
+for (let i = 0; i < 256; ++i) {
+  byteToHex.push((i + 256).toString(16).slice(1));
+}
+function unsafeStringify(arr, offset = 0) {
+  return (byteToHex[arr[offset + 0]] + byteToHex[arr[offset + 1]] + byteToHex[arr[offset + 2]] + byteToHex[arr[offset + 3]] + "-" + byteToHex[arr[offset + 4]] + byteToHex[arr[offset + 5]] + "-" + byteToHex[arr[offset + 6]] + byteToHex[arr[offset + 7]] + "-" + byteToHex[arr[offset + 8]] + byteToHex[arr[offset + 9]] + "-" + byteToHex[arr[offset + 10]] + byteToHex[arr[offset + 11]] + byteToHex[arr[offset + 12]] + byteToHex[arr[offset + 13]] + byteToHex[arr[offset + 14]] + byteToHex[arr[offset + 15]]).toLowerCase();
+}
+
+// ../../node_modules/.pnpm/uuid@14.0.1/node_modules/uuid/dist-node/rng.js
+var rnds8 = new Uint8Array(16);
+function rng() {
+  return crypto.getRandomValues(rnds8);
+}
+
+// ../../node_modules/.pnpm/uuid@14.0.1/node_modules/uuid/dist-node/v4.js
+function v4(options, buf, offset) {
+  if (!buf && !options && crypto.randomUUID) {
+    return crypto.randomUUID();
+  }
+  return _v4(options, buf, offset);
+}
+function _v4(options, buf, offset) {
+  options = options || {};
+  const rnds = options.random ?? options.rng?.() ?? rng();
+  if (rnds.length < 16) {
+    throw new Error("Random bytes length must be >= 16");
+  }
+  rnds[6] = rnds[6] & 15 | 64;
+  rnds[8] = rnds[8] & 63 | 128;
+  if (buf) {
+    offset = offset || 0;
+    if (offset < 0 || offset + 16 > buf.length) {
+      throw new RangeError(`UUID byte range ${offset}:${offset + 15} is out of buffer bounds`);
+    }
+    for (let i = 0; i < 16; ++i) {
+      buf[offset + i] = rnds[i];
+    }
+    return buf;
+  }
+  return unsafeStringify(rnds);
+}
+var v4_default = v4;
+
+// src/correlationId.ts
+var CorrelationId = class _CorrelationId {
+  constructor(value) {
+    this.value = value;
+  }
+  value;
+  static create() {
+    return new _CorrelationId(v4_default());
+  }
+  static fromString(value) {
+    if (isNonBlank(value)) {
+      return new _CorrelationId(value);
+    }
+    throw new import_detailed_error2.DetailedError({
+      code: "INVALID_BLANK_CORRELATION_ID" /* INVALID_BLANK_CORRELATION_ID */,
+      message: "correlationId must be a non-blank string",
+      functionName: "CorrelationId.fromString",
+      details: { value }
+    });
+  }
+  /** Never throws for a primitive string or undefined: blank or missing values fall back to a generated id. */
+  static fromStringOrCreate(value) {
+    if (isNonBlank(value)) {
+      return _CorrelationId.fromString(value);
+    }
+    return _CorrelationId.create();
+  }
+  toString() {
+    return this.value;
+  }
+};
+
+// src/requestId.ts
+var import_detailed_error3 = require("@couimet/detailed-error");
+var RequestId = class _RequestId {
+  constructor(value) {
+    this.value = value;
+  }
+  value;
+  static create() {
+    return new _RequestId(v4_default());
+  }
+  static fromString(value) {
+    if (isNonBlank(value)) {
+      return new _RequestId(value);
+    }
+    throw new import_detailed_error3.DetailedError({
+      code: "INVALID_BLANK_REQUEST_ID" /* INVALID_BLANK_REQUEST_ID */,
+      message: "requestId must be a non-blank string",
+      functionName: "RequestId.fromString",
+      details: { value }
+    });
+  }
+  /** Never throws for a primitive string or undefined: blank or missing values fall back to a generated id. */
+  static fromStringOrCreate(value) {
+    if (isNonBlank(value)) {
+      return _RequestId.fromString(value);
+    }
+    return _RequestId.create();
+  }
+  toString() {
+    return this.value;
+  }
+};
+
+// src/executionContext.ts
+var import_detailed_error4 = require("@couimet/detailed-error");
+var import_api = require("@opentelemetry/api");
+var import_context_async_hooks = require("@opentelemetry/context-async-hooks");
+var EXECUTION_CONTEXT_KEY = (0, import_api.createContextKey)("ExecutionContext");
+function assertContextAttributes(attributes, functionName) {
+  if (attributes === void 0) {
+    return;
+  }
+  const isRecord = attributes !== null && typeof attributes === "object" && !Array.isArray(attributes);
+  if (!isRecord) {
+    throw new import_detailed_error4.DetailedError({
+      code: "INVALID_CONTEXT_ATTRIBUTES" /* INVALID_CONTEXT_ATTRIBUTES */,
+      message: "attributes must be a record of string keys to unknown values",
+      functionName,
+      details: {}
+    });
+  }
+}
+var ExecutionContext = class _ExecutionContext {
+  static contextInitialized = false;
+  /* istanbul ignore next */
+  constructor() {
+  }
+  /**
+   * Installs the global context manager exactly once. Idempotent: later calls
+   * are a no-op once installed. Throws when another component already owns the
+   * global manager slot, because the package then cannot guarantee that async
+   * work inherits the primed ids and failing loud beats silent loss of ids.
+   */
+  static ensureContextManagerInitialized() {
+    if (_ExecutionContext.contextInitialized) {
+      return;
+    }
+    const manager = new import_context_async_hooks.AsyncLocalStorageContextManager().enable();
+    const registered = import_api.context.setGlobalContextManager(manager);
+    if (!registered) {
+      manager.disable();
+      throw new import_detailed_error4.DetailedError({
+        code: "CONTEXT_MANAGER_REGISTRATION_FAILED" /* CONTEXT_MANAGER_REGISTRATION_FAILED */,
+        message: "a global context manager is already registered",
+        functionName: "ExecutionContext.ensureContextManagerInitialized",
+        details: {}
+      });
+    }
+    _ExecutionContext.contextInitialized = true;
+  }
+  static getStore() {
+    return import_api.context.active().getValue(EXECUTION_CONTEXT_KEY);
+  }
+  /**
+   * Primes the execution context; anything previously set gets wiped.
+   * Call sites are the app bootstrap, middleware priming the context from a
+   * request, and timer runs scoping a single execution.
+   */
+  static run(data, fn) {
+    this.ensureContextManagerInitialized();
+    assertContextAttributes(data.attributes, "ExecutionContext.run");
+    const newContext = {
+      correlationId: CorrelationId.fromStringOrCreate(data.correlationId),
+      requestId: RequestId.fromStringOrCreate(data.requestId),
+      attributes: data.attributes ?? {}
+    };
+    const ctx = import_api.context.active().setValue(EXECUTION_CONTEXT_KEY, newContext);
+    return import_api.context.with(ctx, fn);
+  }
+  static isActive() {
+    return this.getStore() !== void 0;
+  }
+  // The ids are guaranteed when the context is active; a missing store is a programming error.
+  static requireStore() {
+    const store = this.getStore();
+    if (store === void 0) {
+      throw new import_detailed_error4.DetailedError({
+        code: "NO_ACTIVE_CONTEXT" /* NO_ACTIVE_CONTEXT */,
+        message: "execution context is not active",
+        functionName: "ExecutionContext.requireStore",
+        details: {}
+      });
+    }
+    return store;
+  }
+  static get correlationId() {
+    return this.requireStore().correlationId;
+  }
+  static get requestId() {
+    return this.requireStore().requestId;
+  }
+  static getAttribute(key) {
+    const attributes = this.getStore()?.attributes;
+    return attributes !== void 0 && Object.prototype.hasOwnProperty.call(attributes, key) ? attributes[key] : void 0;
+  }
+  static addAttributes(attrs) {
+    assertContextAttributes(attrs, "ExecutionContext.addAttributes");
+    const store = this.getStore();
+    if (!store) return;
+    store.attributes = {
+      ...store.attributes,
+      ...attrs
+    };
+  }
+  static getAttributes() {
+    return this.getStore()?.attributes ?? {};
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CorrelationId,
+  ExecutionContext,
+  ExecutionContextErrorCodes,
+  RequestId
+});

package/dist/index.mjs

@@ -0,0 +1,251 @@
+// src/executionContextErrorCodes.ts
+var ExecutionContextErrorCodes = /* @__PURE__ */ ((ExecutionContextErrorCodes2) => {
+  ExecutionContextErrorCodes2["INVALID_BLANK_CORRELATION_ID"] = "INVALID_BLANK_CORRELATION_ID";
+  ExecutionContextErrorCodes2["INVALID_BLANK_REQUEST_ID"] = "INVALID_BLANK_REQUEST_ID";
+  ExecutionContextErrorCodes2["INVALID_CONTEXT_ATTRIBUTES"] = "INVALID_CONTEXT_ATTRIBUTES";
+  ExecutionContextErrorCodes2["INVALID_STRING_TYPE"] = "INVALID_STRING_TYPE";
+  ExecutionContextErrorCodes2["NO_ACTIVE_CONTEXT"] = "NO_ACTIVE_CONTEXT";
+  ExecutionContextErrorCodes2["CONTEXT_MANAGER_REGISTRATION_FAILED"] = "CONTEXT_MANAGER_REGISTRATION_FAILED";
+  return ExecutionContextErrorCodes2;
+})(ExecutionContextErrorCodes || {});
+
+// src/isNonBlank.ts
+import { DetailedError } from "@couimet/detailed-error";
+var isNonBlank = (value) => {
+  if (value === void 0) {
+    return false;
+  }
+  if (typeof value !== "string") {
+    throw new DetailedError({
+      code: "INVALID_STRING_TYPE" /* INVALID_STRING_TYPE */,
+      message: "expected a primitive string or undefined",
+      functionName: "isNonBlank",
+      details: {}
+    });
+  }
+  return value.trim() !== "";
+};
+
+// src/correlationId.ts
+import { DetailedError as DetailedError2 } from "@couimet/detailed-error";
+
+// ../../node_modules/.pnpm/uuid@14.0.1/node_modules/uuid/dist-node/stringify.js
+var byteToHex = [];
+for (let i = 0; i < 256; ++i) {
+  byteToHex.push((i + 256).toString(16).slice(1));
+}
+function unsafeStringify(arr, offset = 0) {
+  return (byteToHex[arr[offset + 0]] + byteToHex[arr[offset + 1]] + byteToHex[arr[offset + 2]] + byteToHex[arr[offset + 3]] + "-" + byteToHex[arr[offset + 4]] + byteToHex[arr[offset + 5]] + "-" + byteToHex[arr[offset + 6]] + byteToHex[arr[offset + 7]] + "-" + byteToHex[arr[offset + 8]] + byteToHex[arr[offset + 9]] + "-" + byteToHex[arr[offset + 10]] + byteToHex[arr[offset + 11]] + byteToHex[arr[offset + 12]] + byteToHex[arr[offset + 13]] + byteToHex[arr[offset + 14]] + byteToHex[arr[offset + 15]]).toLowerCase();
+}
+
+// ../../node_modules/.pnpm/uuid@14.0.1/node_modules/uuid/dist-node/rng.js
+var rnds8 = new Uint8Array(16);
+function rng() {
+  return crypto.getRandomValues(rnds8);
+}
+
+// ../../node_modules/.pnpm/uuid@14.0.1/node_modules/uuid/dist-node/v4.js
+function v4(options, buf, offset) {
+  if (!buf && !options && crypto.randomUUID) {
+    return crypto.randomUUID();
+  }
+  return _v4(options, buf, offset);
+}
+function _v4(options, buf, offset) {
+  options = options || {};
+  const rnds = options.random ?? options.rng?.() ?? rng();
+  if (rnds.length < 16) {
+    throw new Error("Random bytes length must be >= 16");
+  }
+  rnds[6] = rnds[6] & 15 | 64;
+  rnds[8] = rnds[8] & 63 | 128;
+  if (buf) {
+    offset = offset || 0;
+    if (offset < 0 || offset + 16 > buf.length) {
+      throw new RangeError(`UUID byte range ${offset}:${offset + 15} is out of buffer bounds`);
+    }
+    for (let i = 0; i < 16; ++i) {
+      buf[offset + i] = rnds[i];
+    }
+    return buf;
+  }
+  return unsafeStringify(rnds);
+}
+var v4_default = v4;
+
+// src/correlationId.ts
+var CorrelationId = class _CorrelationId {
+  constructor(value) {
+    this.value = value;
+  }
+  value;
+  static create() {
+    return new _CorrelationId(v4_default());
+  }
+  static fromString(value) {
+    if (isNonBlank(value)) {
+      return new _CorrelationId(value);
+    }
+    throw new DetailedError2({
+      code: "INVALID_BLANK_CORRELATION_ID" /* INVALID_BLANK_CORRELATION_ID */,
+      message: "correlationId must be a non-blank string",
+      functionName: "CorrelationId.fromString",
+      details: { value }
+    });
+  }
+  /** Never throws for a primitive string or undefined: blank or missing values fall back to a generated id. */
+  static fromStringOrCreate(value) {
+    if (isNonBlank(value)) {
+      return _CorrelationId.fromString(value);
+    }
+    return _CorrelationId.create();
+  }
+  toString() {
+    return this.value;
+  }
+};
+
+// src/requestId.ts
+import { DetailedError as DetailedError3 } from "@couimet/detailed-error";
+var RequestId = class _RequestId {
+  constructor(value) {
+    this.value = value;
+  }
+  value;
+  static create() {
+    return new _RequestId(v4_default());
+  }
+  static fromString(value) {
+    if (isNonBlank(value)) {
+      return new _RequestId(value);
+    }
+    throw new DetailedError3({
+      code: "INVALID_BLANK_REQUEST_ID" /* INVALID_BLANK_REQUEST_ID */,
+      message: "requestId must be a non-blank string",
+      functionName: "RequestId.fromString",
+      details: { value }
+    });
+  }
+  /** Never throws for a primitive string or undefined: blank or missing values fall back to a generated id. */
+  static fromStringOrCreate(value) {
+    if (isNonBlank(value)) {
+      return _RequestId.fromString(value);
+    }
+    return _RequestId.create();
+  }
+  toString() {
+    return this.value;
+  }
+};
+
+// src/executionContext.ts
+import { DetailedError as DetailedError4 } from "@couimet/detailed-error";
+import { context, createContextKey } from "@opentelemetry/api";
+import { AsyncLocalStorageContextManager } from "@opentelemetry/context-async-hooks";
+var EXECUTION_CONTEXT_KEY = createContextKey("ExecutionContext");
+function assertContextAttributes(attributes, functionName) {
+  if (attributes === void 0) {
+    return;
+  }
+  const isRecord = attributes !== null && typeof attributes === "object" && !Array.isArray(attributes);
+  if (!isRecord) {
+    throw new DetailedError4({
+      code: "INVALID_CONTEXT_ATTRIBUTES" /* INVALID_CONTEXT_ATTRIBUTES */,
+      message: "attributes must be a record of string keys to unknown values",
+      functionName,
+      details: {}
+    });
+  }
+}
+var ExecutionContext = class _ExecutionContext {
+  static contextInitialized = false;
+  /* istanbul ignore next */
+  constructor() {
+  }
+  /**
+   * Installs the global context manager exactly once. Idempotent: later calls
+   * are a no-op once installed. Throws when another component already owns the
+   * global manager slot, because the package then cannot guarantee that async
+   * work inherits the primed ids and failing loud beats silent loss of ids.
+   */
+  static ensureContextManagerInitialized() {
+    if (_ExecutionContext.contextInitialized) {
+      return;
+    }
+    const manager = new AsyncLocalStorageContextManager().enable();
+    const registered = context.setGlobalContextManager(manager);
+    if (!registered) {
+      manager.disable();
+      throw new DetailedError4({
+        code: "CONTEXT_MANAGER_REGISTRATION_FAILED" /* CONTEXT_MANAGER_REGISTRATION_FAILED */,
+        message: "a global context manager is already registered",
+        functionName: "ExecutionContext.ensureContextManagerInitialized",
+        details: {}
+      });
+    }
+    _ExecutionContext.contextInitialized = true;
+  }
+  static getStore() {
+    return context.active().getValue(EXECUTION_CONTEXT_KEY);
+  }
+  /**
+   * Primes the execution context; anything previously set gets wiped.
+   * Call sites are the app bootstrap, middleware priming the context from a
+   * request, and timer runs scoping a single execution.
+   */
+  static run(data, fn) {
+    this.ensureContextManagerInitialized();
+    assertContextAttributes(data.attributes, "ExecutionContext.run");
+    const newContext = {
+      correlationId: CorrelationId.fromStringOrCreate(data.correlationId),
+      requestId: RequestId.fromStringOrCreate(data.requestId),
+      attributes: data.attributes ?? {}
+    };
+    const ctx = context.active().setValue(EXECUTION_CONTEXT_KEY, newContext);
+    return context.with(ctx, fn);
+  }
+  static isActive() {
+    return this.getStore() !== void 0;
+  }
+  // The ids are guaranteed when the context is active; a missing store is a programming error.
+  static requireStore() {
+    const store = this.getStore();
+    if (store === void 0) {
+      throw new DetailedError4({
+        code: "NO_ACTIVE_CONTEXT" /* NO_ACTIVE_CONTEXT */,
+        message: "execution context is not active",
+        functionName: "ExecutionContext.requireStore",
+        details: {}
+      });
+    }
+    return store;
+  }
+  static get correlationId() {
+    return this.requireStore().correlationId;
+  }
+  static get requestId() {
+    return this.requireStore().requestId;
+  }
+  static getAttribute(key) {
+    const attributes = this.getStore()?.attributes;
+    return attributes !== void 0 && Object.prototype.hasOwnProperty.call(attributes, key) ? attributes[key] : void 0;
+  }
+  static addAttributes(attrs) {
+    assertContextAttributes(attrs, "ExecutionContext.addAttributes");
+    const store = this.getStore();
+    if (!store) return;
+    store.attributes = {
+      ...store.attributes,
+      ...attrs
+    };
+  }
+  static getAttributes() {
+    return this.getStore()?.attributes ?? {};
+  }
+};
+export {
+  CorrelationId,
+  ExecutionContext,
+  ExecutionContextErrorCodes,
+  RequestId
+};

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@couimet/execution-context",
+  "version": "0.1.0",
+  "description": "Execution context carrying correlation id, request id, and typed attributes across async boundaries",
+  "homepage": "https://github.com/couimet/ts-npm-packages/tree/main/packages/execution-context#readme",
+  "bugs": {
+    "url": "https://github.com/couimet/ts-npm-packages/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:couimet/ts-npm-packages.git",
+    "directory": "packages/execution-context"
+  },
+  "license": "MIT",
+  "author": "Charles Ouimet <charles.ouimet@gmail.com>",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "prettier": "@couimet/eslint-config/prettier",
+  "dependencies": {
+    "@opentelemetry/context-async-hooks": ">=2.10.0",
+    "uuid": "^14.0.1"
+  },
+  "devDependencies": {
+    "@babel/preset-env": "^7.29.7",
+    "@opentelemetry/api": ">=1.9.1",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^26.2.0",
+    "babel-jest": "^29.7.0",
+    "eslint": "^10.8.1",
+    "jest": "^29.7.0",
+    "prettier": "^3.9.6",
+    "ts-jest": "^29.4.12",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "@couimet/detailed-error": "1.0.0",
+    "@couimet/dynamic-testing": "1.0.1",
+    "@couimet/detailed-error-testing": "0.1.5",
+    "@couimet/eslint-config": "1.3.0"
+  },
+  "peerDependencies": {
+    "@couimet/detailed-error": ">=1.0.0",
+    "@opentelemetry/api": ">=1.9.1"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "clean": "rm -rf dist coverage *.tsbuildinfo",
+    "clean:all": "pnpm clean && rm -rf node_modules .eslintcache *.log",
+    "clean:deps": "rm -rf node_modules",
+    "format": "prettier --check .",
+    "test": "jest --coverage",
+    "typecheck": "tsc --noEmit"
+  }
+}