@birtalanrobert/context 0.1.0

package/NOTICE

@@ -0,0 +1,45 @@
+mortar
+Copyright (C) 2026 Robert Birtalan
+
+This program is free software: you can redistribute it and/or modify it under
+the terms of the GNU Affero General Public License as published by the Free
+Software Foundation, either version 3 of the License, or (at your option) any
+later version.
+
+This program is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License along
+with this program. If not, see <https://www.gnu.org/licenses/>.
+
+--------------------------------------------------------------------------------
+
+RIGHTS RESERVED BY THE COPYRIGHT HOLDER
+
+The AGPL is a grant from the copyright holder to everyone else. The copyright
+holder is not a licensee of their own work, and is therefore not bound by these
+terms.
+
+Robert Birtalan, as sole copyright holder, retains the right to use, modify and
+distribute this software under any other terms, including within closed-source
+and commercial products, without triggering any obligation under the AGPL.
+
+Commercial licences for third parties who cannot or do not wish to comply with
+the AGPL are available on request.
+
+--------------------------------------------------------------------------------
+
+CONTRIBUTIONS
+
+Contributions are not currently accepted.
+
+This is deliberate and load-bearing. A contributor retains copyright in their
+contribution unless they assign it. Accepting outside contributions without a
+copyright assignment or a contributor licence agreement would mean the project
+was no longer wholly owned by one copyright holder — and the reserved rights
+above would no longer apply to those parts, because one cannot relicense code
+one does not own.
+
+Should contributions be accepted in future, a CLA assigning copyright to the
+maintainer is a prerequisite, not a formality.

package/README.md

@@ -0,0 +1,3 @@
+# @birtalanrobert/context
+
+AsyncLocalStorage request context

package/dist/context.d.ts

@@ -0,0 +1,67 @@
+import type { Actor, ContextSource, RequestContext } from './types';
+export interface CreateContextOptions {
+    requestId?: string;
+    correlationId?: string;
+    tenantId?: string;
+    actor?: Actor;
+    locale?: string;
+    ip?: string;
+    userAgent?: string;
+    source?: ContextSource;
+}
+/** Builds a context without entering it. Rarely needed directly. */
+export declare function createContext(options?: CreateContextOptions): RequestContext;
+/**
+ * Runs `fn` inside a fresh context. Everything called from `fn`, synchronously
+ * or asynchronously, sees that context.
+ */
+export declare function runInContext<T>(options: CreateContextOptions, fn: () => T): T;
+/** Runs `fn` inside an already-built context. */
+export declare function runWithContext<T>(context: RequestContext, fn: () => T): T;
+/** The current context, or undefined outside one. */
+export declare function getContext(): RequestContext | undefined;
+/**
+ * The current context, throwing if there is none.
+ *
+ * Use where the absence of a context is a programming error — a tenant-scoped
+ * repository, for instance, must never run unscoped.
+ */
+export declare function requireContext(): RequestContext;
+/** The current tenant, or undefined. */
+export declare function getTenantId(): string | undefined;
+/**
+ * The current tenant, throwing if absent.
+ *
+ * This is a security primitive: a query that should be tenant-scoped must fail
+ * loudly rather than quietly returning every tenant's rows.
+ */
+export declare function requireTenantId(): string;
+export declare function getActor(): Actor | undefined;
+export declare function requireActor(): Actor;
+export declare function getRequestId(): string | undefined;
+export declare function getCorrelationId(): string | undefined;
+export declare function getLocale(): string | undefined;
+/** Milliseconds since the current unit of work started. */
+export declare function elapsedMs(): number | undefined;
+/**
+ * Mutates the active context.
+ *
+ * Deliberately narrow: only the fields that are genuinely resolved *during* a
+ * request — the tenant after resolution, the actor after authentication, the
+ * locale after negotiation — are settable. Identity fields are immutable.
+ */
+export declare function setContextValues(values: Pick<RequestContext, 'tenantId' | 'actor' | 'locale'>): void;
+export declare function setAttribute(key: string, value: unknown): void;
+export declare function getAttribute<T = unknown>(key: string): T | undefined;
+/**
+ * Runs `fn` in a child context inheriting correlation from the current one.
+ *
+ * The mechanism by which a background job spawned from a request stays
+ * traceable back to it.
+ */
+export declare function runInChildContext<T>(options: CreateContextOptions, fn: () => T): T;
+/**
+ * The fields worth attaching to every log line and propagating to a job.
+ */
+export declare function contextSnapshot(): Record<string, unknown>;
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAIpE,MAAM,WAAW,oBAAoB;IACnC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AAED,oEAAoE;AACpE,wBAAgB,aAAa,CAAC,OAAO,GAAE,oBAAyB,GAAG,cAAc,CAchF;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,OAAO,EAAE,oBAAoB,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAE7E;AAED,iDAAiD;AACjD,wBAAgB,cAAc,CAAC,CAAC,EAAE,OAAO,EAAE,cAAc,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAEzE;AAED,qDAAqD;AACrD,wBAAgB,UAAU,IAAI,cAAc,GAAG,SAAS,CAEvD;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,IAAI,cAAc,CAS/C;AAED,wCAAwC;AACxC,wBAAgB,WAAW,IAAI,MAAM,GAAG,SAAS,CAEhD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,IAAI,MAAM,CASxC;AAED,wBAAgB,QAAQ,IAAI,KAAK,GAAG,SAAS,CAE5C;AAED,wBAAgB,YAAY,IAAI,KAAK,CAIpC;AAED,wBAAgB,YAAY,IAAI,MAAM,GAAG,SAAS,CAEjD;AAED,wBAAgB,gBAAgB,IAAI,MAAM,GAAG,SAAS,CAErD;AAED,wBAAgB,SAAS,IAAI,MAAM,GAAG,SAAS,CAE9C;AAED,2DAA2D;AAC3D,wBAAgB,SAAS,IAAI,MAAM,GAAG,SAAS,CAG9C;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,IAAI,CAAC,cAAc,EAAE,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAC,GAC5D,IAAI,CAMN;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAE9D;AAED,wBAAgB,YAAY,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAEpE;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,OAAO,EAAE,oBAAoB,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAYlF;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAWzD"}

package/dist/context.js

@@ -0,0 +1,166 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createContext = createContext;
+exports.runInContext = runInContext;
+exports.runWithContext = runWithContext;
+exports.getContext = getContext;
+exports.requireContext = requireContext;
+exports.getTenantId = getTenantId;
+exports.requireTenantId = requireTenantId;
+exports.getActor = getActor;
+exports.requireActor = requireActor;
+exports.getRequestId = getRequestId;
+exports.getCorrelationId = getCorrelationId;
+exports.getLocale = getLocale;
+exports.elapsedMs = elapsedMs;
+exports.setContextValues = setContextValues;
+exports.setAttribute = setAttribute;
+exports.getAttribute = getAttribute;
+exports.runInChildContext = runInChildContext;
+exports.contextSnapshot = contextSnapshot;
+const node_async_hooks_1 = require("node:async_hooks");
+const node_crypto_1 = require("node:crypto");
+const storage = new node_async_hooks_1.AsyncLocalStorage();
+/** Builds a context without entering it. Rarely needed directly. */
+function createContext(options = {}) {
+    const requestId = options.requestId ?? (0, node_crypto_1.randomUUID)();
+    return {
+        requestId,
+        correlationId: options.correlationId ?? requestId,
+        tenantId: options.tenantId,
+        actor: options.actor,
+        locale: options.locale,
+        ip: options.ip,
+        userAgent: options.userAgent,
+        source: options.source ?? 'internal',
+        startedAt: Date.now(),
+        attributes: new Map(),
+    };
+}
+/**
+ * Runs `fn` inside a fresh context. Everything called from `fn`, synchronously
+ * or asynchronously, sees that context.
+ */
+function runInContext(options, fn) {
+    return storage.run(createContext(options), fn);
+}
+/** Runs `fn` inside an already-built context. */
+function runWithContext(context, fn) {
+    return storage.run(context, fn);
+}
+/** The current context, or undefined outside one. */
+function getContext() {
+    return storage.getStore();
+}
+/**
+ * The current context, throwing if there is none.
+ *
+ * Use where the absence of a context is a programming error — a tenant-scoped
+ * repository, for instance, must never run unscoped.
+ */
+function requireContext() {
+    const context = storage.getStore();
+    if (!context) {
+        throw new Error('No request context is active. Wrap this work in runInContext(), or use getContext() ' +
+            'if running outside a request is legitimate here.');
+    }
+    return context;
+}
+/** The current tenant, or undefined. */
+function getTenantId() {
+    return storage.getStore()?.tenantId;
+}
+/**
+ * The current tenant, throwing if absent.
+ *
+ * This is a security primitive: a query that should be tenant-scoped must fail
+ * loudly rather than quietly returning every tenant's rows.
+ */
+function requireTenantId() {
+    const tenantId = storage.getStore()?.tenantId;
+    if (!tenantId) {
+        throw new Error('No tenant is bound to the current context. A tenant-scoped operation cannot proceed ' +
+            'without one — this would otherwise read across tenants.');
+    }
+    return tenantId;
+}
+function getActor() {
+    return storage.getStore()?.actor;
+}
+function requireActor() {
+    const actor = storage.getStore()?.actor;
+    if (!actor)
+        throw new Error('No actor is bound to the current context.');
+    return actor;
+}
+function getRequestId() {
+    return storage.getStore()?.requestId;
+}
+function getCorrelationId() {
+    return storage.getStore()?.correlationId;
+}
+function getLocale() {
+    return storage.getStore()?.locale;
+}
+/** Milliseconds since the current unit of work started. */
+function elapsedMs() {
+    const context = storage.getStore();
+    return context ? Date.now() - context.startedAt : undefined;
+}
+/**
+ * Mutates the active context.
+ *
+ * Deliberately narrow: only the fields that are genuinely resolved *during* a
+ * request — the tenant after resolution, the actor after authentication, the
+ * locale after negotiation — are settable. Identity fields are immutable.
+ */
+function setContextValues(values) {
+    const context = storage.getStore();
+    if (!context)
+        return;
+    if (values.tenantId !== undefined)
+        context.tenantId = values.tenantId;
+    if (values.actor !== undefined)
+        context.actor = values.actor;
+    if (values.locale !== undefined)
+        context.locale = values.locale;
+}
+function setAttribute(key, value) {
+    storage.getStore()?.attributes.set(key, value);
+}
+function getAttribute(key) {
+    return storage.getStore()?.attributes.get(key);
+}
+/**
+ * Runs `fn` in a child context inheriting correlation from the current one.
+ *
+ * The mechanism by which a background job spawned from a request stays
+ * traceable back to it.
+ */
+function runInChildContext(options, fn) {
+    const parent = storage.getStore();
+    return runInContext({
+        correlationId: parent?.correlationId,
+        tenantId: parent?.tenantId,
+        actor: parent?.actor,
+        locale: parent?.locale,
+        ...options,
+    }, fn);
+}
+/**
+ * The fields worth attaching to every log line and propagating to a job.
+ */
+function contextSnapshot() {
+    const context = storage.getStore();
+    if (!context)
+        return {};
+    return {
+        requestId: context.requestId,
+        correlationId: context.correlationId,
+        ...(context.tenantId ? { tenantId: context.tenantId } : {}),
+        ...(context.actor ? { actorId: context.actor.id, actorType: context.actor.type } : {}),
+        ...(context.actor?.impersonatedBy ? { impersonatedBy: context.actor.impersonatedBy } : {}),
+        source: context.source,
+    };
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export type { Actor, ContextSource, RequestContext } from './types';
+export { contextSnapshot, createContext, elapsedMs, getActor, getAttribute, getContext, getCorrelationId, getLocale, getRequestId, getTenantId, requireActor, requireContext, requireTenantId, runInChildContext, runInContext, runWithContext, setAttribute, setContextValues, type CreateContextOptions, } from './context';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AACpE,OAAO,EACL,eAAe,EACf,aAAa,EACb,SAAS,EACT,QAAQ,EACR,YAAY,EACZ,UAAU,EACV,gBAAgB,EAChB,SAAS,EACT,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,KAAK,oBAAoB,GAC1B,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setContextValues = exports.setAttribute = exports.runWithContext = exports.runInContext = exports.runInChildContext = exports.requireTenantId = exports.requireContext = exports.requireActor = exports.getTenantId = exports.getRequestId = exports.getLocale = exports.getCorrelationId = exports.getContext = exports.getAttribute = exports.getActor = exports.elapsedMs = exports.createContext = exports.contextSnapshot = void 0;
+var context_1 = require("./context");
+Object.defineProperty(exports, "contextSnapshot", { enumerable: true, get: function () { return context_1.contextSnapshot; } });
+Object.defineProperty(exports, "createContext", { enumerable: true, get: function () { return context_1.createContext; } });
+Object.defineProperty(exports, "elapsedMs", { enumerable: true, get: function () { return context_1.elapsedMs; } });
+Object.defineProperty(exports, "getActor", { enumerable: true, get: function () { return context_1.getActor; } });
+Object.defineProperty(exports, "getAttribute", { enumerable: true, get: function () { return context_1.getAttribute; } });
+Object.defineProperty(exports, "getContext", { enumerable: true, get: function () { return context_1.getContext; } });
+Object.defineProperty(exports, "getCorrelationId", { enumerable: true, get: function () { return context_1.getCorrelationId; } });
+Object.defineProperty(exports, "getLocale", { enumerable: true, get: function () { return context_1.getLocale; } });
+Object.defineProperty(exports, "getRequestId", { enumerable: true, get: function () { return context_1.getRequestId; } });
+Object.defineProperty(exports, "getTenantId", { enumerable: true, get: function () { return context_1.getTenantId; } });
+Object.defineProperty(exports, "requireActor", { enumerable: true, get: function () { return context_1.requireActor; } });
+Object.defineProperty(exports, "requireContext", { enumerable: true, get: function () { return context_1.requireContext; } });
+Object.defineProperty(exports, "requireTenantId", { enumerable: true, get: function () { return context_1.requireTenantId; } });
+Object.defineProperty(exports, "runInChildContext", { enumerable: true, get: function () { return context_1.runInChildContext; } });
+Object.defineProperty(exports, "runInContext", { enumerable: true, get: function () { return context_1.runInContext; } });
+Object.defineProperty(exports, "runWithContext", { enumerable: true, get: function () { return context_1.runWithContext; } });
+Object.defineProperty(exports, "setAttribute", { enumerable: true, get: function () { return context_1.setAttribute; } });
+Object.defineProperty(exports, "setContextValues", { enumerable: true, get: function () { return context_1.setContextValues; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AACA,qCAoBmB;AAnBjB,0GAAA,eAAe,OAAA;AACf,wGAAA,aAAa,OAAA;AACb,oGAAA,SAAS,OAAA;AACT,mGAAA,QAAQ,OAAA;AACR,uGAAA,YAAY,OAAA;AACZ,qGAAA,UAAU,OAAA;AACV,2GAAA,gBAAgB,OAAA;AAChB,oGAAA,SAAS,OAAA;AACT,uGAAA,YAAY,OAAA;AACZ,sGAAA,WAAW,OAAA;AACX,uGAAA,YAAY,OAAA;AACZ,yGAAA,cAAc,OAAA;AACd,0GAAA,eAAe,OAAA;AACf,4GAAA,iBAAiB,OAAA;AACjB,uGAAA,YAAY,OAAA;AACZ,yGAAA,cAAc,OAAA;AACd,uGAAA,YAAY,OAAA;AACZ,2GAAA,gBAAgB,OAAA"}

package/dist/types.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The ambient facts about the work currently in flight.
+ *
+ * Carried through AsyncLocalStorage rather than threaded through every
+ * function signature, because these values are needed by logging, auditing,
+ * tenant scoping and error reporting — layers that should not force every
+ * intermediate function to know about them.
+ */
+export interface RequestContext {
+    /** Unique per inbound request or job execution. */
+    readonly requestId: string;
+    /**
+     * Correlates work across service boundaries and background jobs. Inherited
+     * from an incoming header where present, otherwise equal to requestId.
+     */
+    readonly correlationId: string;
+    /** The tenant this work belongs to, once resolved. */
+    tenantId?: string;
+    /** The authenticated principal, once resolved. */
+    actor?: Actor;
+    /** Resolved locale, e.g. 'ro-RO'. */
+    locale?: string;
+    /** Client address, for audit and rate limiting. */
+    ip?: string;
+    /** Client user agent, for audit. */
+    userAgent?: string;
+    /** Where this unit of work came from. */
+    readonly source: ContextSource;
+    /** When the unit of work started, for duration measurement. */
+    readonly startedAt: number;
+    /** Free-form values attached by application code. */
+    readonly attributes: Map<string, unknown>;
+}
+export type ContextSource = 'http' | 'job' | 'cli' | 'test' | 'internal';
+export interface Actor {
+    readonly id: string;
+    /**
+     * `user` is a human with an account; `client` is a link-authenticated party
+     * with no account (a guest, a candidate, a tenant of a landlord); `system`
+     * is scheduled or internal work; `service` is a machine credential.
+     */
+    readonly type: 'user' | 'client' | 'system' | 'service';
+    readonly displayName?: string;
+    readonly roles?: readonly string[];
+    /** Set when an operator is impersonating; the audit trail records both. */
+    readonly impersonatedBy?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,mDAAmD;IACnD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,sDAAsD;IACtD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kDAAkD;IAClD,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,qCAAqC;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,oCAAoC;IACpC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yCAAyC;IACzC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,qDAAqD;IACrD,QAAQ,CAAC,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC3C;AAED,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,GAAG,UAAU,CAAC;AAEzE,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;IACxD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,2EAA2E;IAC3E,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC"}

package/dist/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

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

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@birtalanrobert/context",
+  "version": "0.1.0",
+  "description": "AsyncLocalStorage request context",
+  "license": "AGPL-3.0-only",
+  "type": "commonjs",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.spec.ts",
+    "!src/**/__tests__",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/birtalanrobert/mortar.git",
+    "directory": "packages/context"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "rm -rf dist *.tsbuildinfo",
+    "typecheck": "tsc -p tsconfig.json"
+  }
+}

package/src/context.ts

@@ -0,0 +1,179 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomUUID } from 'node:crypto';
+import type { Actor, ContextSource, RequestContext } from './types';
+
+const storage = new AsyncLocalStorage<RequestContext>();
+
+export interface CreateContextOptions {
+  requestId?: string;
+  correlationId?: string;
+  tenantId?: string;
+  actor?: Actor;
+  locale?: string;
+  ip?: string;
+  userAgent?: string;
+  source?: ContextSource;
+}
+
+/** Builds a context without entering it. Rarely needed directly. */
+export function createContext(options: CreateContextOptions = {}): RequestContext {
+  const requestId = options.requestId ?? randomUUID();
+  return {
+    requestId,
+    correlationId: options.correlationId ?? requestId,
+    tenantId: options.tenantId,
+    actor: options.actor,
+    locale: options.locale,
+    ip: options.ip,
+    userAgent: options.userAgent,
+    source: options.source ?? 'internal',
+    startedAt: Date.now(),
+    attributes: new Map<string, unknown>(),
+  };
+}
+
+/**
+ * Runs `fn` inside a fresh context. Everything called from `fn`, synchronously
+ * or asynchronously, sees that context.
+ */
+export function runInContext<T>(options: CreateContextOptions, fn: () => T): T {
+  return storage.run(createContext(options), fn);
+}
+
+/** Runs `fn` inside an already-built context. */
+export function runWithContext<T>(context: RequestContext, fn: () => T): T {
+  return storage.run(context, fn);
+}
+
+/** The current context, or undefined outside one. */
+export function getContext(): RequestContext | undefined {
+  return storage.getStore();
+}
+
+/**
+ * The current context, throwing if there is none.
+ *
+ * Use where the absence of a context is a programming error — a tenant-scoped
+ * repository, for instance, must never run unscoped.
+ */
+export function requireContext(): RequestContext {
+  const context = storage.getStore();
+  if (!context) {
+    throw new Error(
+      'No request context is active. Wrap this work in runInContext(), or use getContext() ' +
+        'if running outside a request is legitimate here.',
+    );
+  }
+  return context;
+}
+
+/** The current tenant, or undefined. */
+export function getTenantId(): string | undefined {
+  return storage.getStore()?.tenantId;
+}
+
+/**
+ * The current tenant, throwing if absent.
+ *
+ * This is a security primitive: a query that should be tenant-scoped must fail
+ * loudly rather than quietly returning every tenant's rows.
+ */
+export function requireTenantId(): string {
+  const tenantId = storage.getStore()?.tenantId;
+  if (!tenantId) {
+    throw new Error(
+      'No tenant is bound to the current context. A tenant-scoped operation cannot proceed ' +
+        'without one — this would otherwise read across tenants.',
+    );
+  }
+  return tenantId;
+}
+
+export function getActor(): Actor | undefined {
+  return storage.getStore()?.actor;
+}
+
+export function requireActor(): Actor {
+  const actor = storage.getStore()?.actor;
+  if (!actor) throw new Error('No actor is bound to the current context.');
+  return actor;
+}
+
+export function getRequestId(): string | undefined {
+  return storage.getStore()?.requestId;
+}
+
+export function getCorrelationId(): string | undefined {
+  return storage.getStore()?.correlationId;
+}
+
+export function getLocale(): string | undefined {
+  return storage.getStore()?.locale;
+}
+
+/** Milliseconds since the current unit of work started. */
+export function elapsedMs(): number | undefined {
+  const context = storage.getStore();
+  return context ? Date.now() - context.startedAt : undefined;
+}
+
+/**
+ * Mutates the active context.
+ *
+ * Deliberately narrow: only the fields that are genuinely resolved *during* a
+ * request — the tenant after resolution, the actor after authentication, the
+ * locale after negotiation — are settable. Identity fields are immutable.
+ */
+export function setContextValues(
+  values: Pick<RequestContext, 'tenantId' | 'actor' | 'locale'>,
+): void {
+  const context = storage.getStore();
+  if (!context) return;
+  if (values.tenantId !== undefined) context.tenantId = values.tenantId;
+  if (values.actor !== undefined) context.actor = values.actor;
+  if (values.locale !== undefined) context.locale = values.locale;
+}
+
+export function setAttribute(key: string, value: unknown): void {
+  storage.getStore()?.attributes.set(key, value);
+}
+
+export function getAttribute<T = unknown>(key: string): T | undefined {
+  return storage.getStore()?.attributes.get(key) as T | undefined;
+}
+
+/**
+ * Runs `fn` in a child context inheriting correlation from the current one.
+ *
+ * The mechanism by which a background job spawned from a request stays
+ * traceable back to it.
+ */
+export function runInChildContext<T>(options: CreateContextOptions, fn: () => T): T {
+  const parent = storage.getStore();
+  return runInContext(
+    {
+      correlationId: parent?.correlationId,
+      tenantId: parent?.tenantId,
+      actor: parent?.actor,
+      locale: parent?.locale,
+      ...options,
+    },
+    fn,
+  );
+}
+
+/**
+ * The fields worth attaching to every log line and propagating to a job.
+ */
+export function contextSnapshot(): Record<string, unknown> {
+  const context = storage.getStore();
+  if (!context) return {};
+  return {
+    requestId: context.requestId,
+    correlationId: context.correlationId,
+    ...(context.tenantId ? { tenantId: context.tenantId } : {}),
+    ...(context.actor ? { actorId: context.actor.id, actorType: context.actor.type } : {}),
+    ...(context.actor?.impersonatedBy ? { impersonatedBy: context.actor.impersonatedBy } : {}),
+    source: context.source,
+  };
+}

package/src/index.ts

@@ -0,0 +1,22 @@
+export type { Actor, ContextSource, RequestContext } from './types';
+export {
+  contextSnapshot,
+  createContext,
+  elapsedMs,
+  getActor,
+  getAttribute,
+  getContext,
+  getCorrelationId,
+  getLocale,
+  getRequestId,
+  getTenantId,
+  requireActor,
+  requireContext,
+  requireTenantId,
+  runInChildContext,
+  runInContext,
+  runWithContext,
+  setAttribute,
+  setContextValues,
+  type CreateContextOptions,
+} from './context';