@nodii/telemetry 0.10.0 → 0.11.0

package/dist/context-adapter/claims.d.ts

@@ -0,0 +1,89 @@
+import type { ActorType, NodiiContext } from "../types.js";
+/**
+ * The minimal verified-claims surface the adapters consume. This is a
+ * STRUCTURAL contract — both `@nodii/auth-sdk`'s `NodiiClaims`
+ * (`sub`/`principalKind`/`roles`/`actor`) and the gRPC
+ * `UserActorEnvelope` map onto it. Every field is optional so the
+ * adapter degrades gracefully when a claim is absent (e.g. an S2S-only
+ * call with no user actor).
+ */
+export interface AdapterClaims {
+    /** Tenant the principal is acting within. NodiiContext.tenant_id. */
+    tenantId?: string | null;
+    /**
+     * Principal id. Becomes NodiiContext.user_id ONLY when the resolved
+     * actor_type is 'user' (the type invariant: user_id is null otherwise).
+     */
+    subjectId?: string | null;
+    /**
+     * Subject kind from the token. Maps to actor_type. Accepts the
+     * auth-sdk `principalKind` vocabulary ('user' | 'customer' | 'agent' |
+     * 'service') plus 'system'; anything unrecognized falls back to
+     * 'service' (the safe non-user, non-agent default).
+     */
+    subjectKind?: string | null;
+    /**
+     * Tenant-defined role names the principal holds. Collapsed to a single
+     * NodiiContext.role via highest-privilege selection.
+     */
+    roles?: readonly string[] | null;
+    /**
+     * Delegation / on-behalf-of claim. The id of the principal this
+     * actor is acting on behalf of (act/obo). Maps to on_behalf_of.
+     */
+    onBehalfOf?: string | null;
+    /** Intent id if one is already active on the inbound call. */
+    intentId?: string | null;
+}
+/**
+ * Default role-privilege ordering, highest first. Used to collapse a
+ * `roles[]` claim down to the single `NodiiContext.role`. There is no
+ * canonical RBAC role ordering elsewhere in nodii-libs (the DB `nodii_*`
+ * roles in db-rls are Postgres roles, not RBAC role names), and the
+ * UserActorEnvelope doc cites "owner" > "admin" > "member" as the
+ * representative ladder — this extends that ladder with the common
+ * management / read-only tiers. Callers with a service-specific ladder
+ * pass `rolePrivilegeOrder` to override it.
+ *
+ * Selection rule: the role appearing EARLIEST in this list wins. A role
+ * not in the list ranks BELOW every listed role (least privilege), so an
+ * unknown custom role never silently outranks a known privileged one.
+ */
+export declare const ROLE_PRIVILEGE_ORDER: readonly string[];
+/**
+ * Collapse a `roles[]` claim to the single highest-privilege role.
+ * Returns `fallback` ('member' by default) when the array is empty/absent.
+ */
+export declare function collapseRolesToHighest(roles: readonly string[] | null | undefined, order?: readonly string[], fallback?: string): string;
+/**
+ * Map a token subject kind to the locked `ActorType` enum. `customer`
+ * (an auth-sdk principalKind) is a user-facing principal → 'user'.
+ * Unrecognized kinds fall back to 'service' (safe non-user default).
+ */
+export declare function deriveActorType(subjectKind?: string | null): ActorType;
+export interface MapClaimsOptions {
+    /**
+     * The inbound `x-request-id` value (header or gRPC metadata). When
+     * absent/empty a fresh uuidv7 is minted — request_id is NEVER empty in
+     * a NodiiContext.
+     */
+    requestId?: string | null;
+    /** Override the default role-privilege ladder. */
+    rolePrivilegeOrder?: readonly string[];
+    /** Override the fallback role when no roles claim is present. */
+    roleFallback?: string;
+    /**
+     * Fallback tenant_id when the claims carry none. NodiiContext.tenant_id
+     * is non-nullable; if neither claim nor fallback supplies it the adapter
+     * throws (a context with no tenant is not safe to set — RLS keys off it).
+     */
+    tenantFallback?: string;
+}
+/**
+ * Build a `NodiiContext` from verified claims + the inbound request_id.
+ * Pure + deterministic given a fixed request_id; the adapters call it
+ * after extracting the request_id (so the generated-uuid path is
+ * observable/testable).
+ */
+export declare function mapClaimsToContext(claims: AdapterClaims, opts?: MapClaimsOptions): NodiiContext;
+//# sourceMappingURL=claims.d.ts.map

package/dist/context-adapter/claims.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claims.d.ts","sourceRoot":"","sources":["../../src/context-adapter/claims.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG3D;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B;;;OAGG;IACH,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAC;IACjC;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,oBAAoB,EAAE,SAAS,MAAM,EAOxC,CAAC;AAEX;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,GAAG,SAAS,EAC3C,KAAK,GAAE,SAAS,MAAM,EAAyB,EAC/C,QAAQ,SAAW,GAClB,MAAM,CAmBR;AASD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAQtE;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,kDAAkD;IAClD,kBAAkB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,iEAAiE;IACjE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,aAAa,EACrB,IAAI,GAAE,gBAAqB,GAC1B,YAAY,CA+Bd"}

package/dist/context-adapter/claims.js

@@ -0,0 +1,113 @@
+// Shared NodiiContext mapping for the entry-seam adapters (D44 § 6.5,
+// D405 context adoption). The Hono middleware (`./hono.ts`) and the gRPC
+// server interceptor (`./grpc.ts`) both funnel through `mapClaimsToContext`
+// so the field mappings are defined exactly once.
+//
+// Operator-LOCKED field mappings (req b3b03fc5, clarification c9906a51,
+// approved 2026-06-25):
+//   - actor_type   — derived from the token's subject kind.
+//   - roles[] → role — NodiiContext.role is singular; collapse roles[] to
+//                      the HIGHEST-privilege role (see ROLE_PRIVILEGE_ORDER).
+//   - on_behalf_of — sourced from the delegation (act/obo) claim.
+//   - request_id   — read from x-request-id; GENERATED (uuidv7) if absent.
+// tenant_id / intent_id / user_id come from the claims; trace activation
+// is handled separately by the adapter (it activates the inbound
+// trace_parent onto the OTel context, never folded into NodiiContext).
+import { uuidv7 } from "../uuid.js";
+/**
+ * Default role-privilege ordering, highest first. Used to collapse a
+ * `roles[]` claim down to the single `NodiiContext.role`. There is no
+ * canonical RBAC role ordering elsewhere in nodii-libs (the DB `nodii_*`
+ * roles in db-rls are Postgres roles, not RBAC role names), and the
+ * UserActorEnvelope doc cites "owner" > "admin" > "member" as the
+ * representative ladder — this extends that ladder with the common
+ * management / read-only tiers. Callers with a service-specific ladder
+ * pass `rolePrivilegeOrder` to override it.
+ *
+ * Selection rule: the role appearing EARLIEST in this list wins. A role
+ * not in the list ranks BELOW every listed role (least privilege), so an
+ * unknown custom role never silently outranks a known privileged one.
+ */
+export const ROLE_PRIVILEGE_ORDER = [
+    "owner",
+    "admin",
+    "manager",
+    "member",
+    "viewer",
+    "guest",
+];
+/**
+ * Collapse a `roles[]` claim to the single highest-privilege role.
+ * Returns `fallback` ('member' by default) when the array is empty/absent.
+ */
+export function collapseRolesToHighest(roles, order = ROLE_PRIVILEGE_ORDER, fallback = "member") {
+    if (!roles || roles.length === 0)
+        return fallback;
+    const rank = (r) => {
+        const i = order.indexOf(r);
+        // Unknown roles rank below every known role (largest index).
+        return i === -1 ? order.length : i;
+    };
+    // Pick the role with the smallest rank index; ties broken by input order.
+    let best = roles[0];
+    let bestRank = rank(best);
+    for (let i = 1; i < roles.length; i++) {
+        const candidate = roles[i];
+        const candidateRank = rank(candidate);
+        if (candidateRank < bestRank) {
+            best = candidate;
+            bestRank = candidateRank;
+        }
+    }
+    return best;
+}
+const ACTOR_TYPES = [
+    "user",
+    "agent",
+    "system",
+    "service",
+];
+/**
+ * Map a token subject kind to the locked `ActorType` enum. `customer`
+ * (an auth-sdk principalKind) is a user-facing principal → 'user'.
+ * Unrecognized kinds fall back to 'service' (safe non-user default).
+ */
+export function deriveActorType(subjectKind) {
+    if (!subjectKind)
+        return "service";
+    const normalized = subjectKind.toLowerCase();
+    if (normalized === "customer")
+        return "user";
+    if (ACTOR_TYPES.includes(normalized)) {
+        return normalized;
+    }
+    return "service";
+}
+/**
+ * Build a `NodiiContext` from verified claims + the inbound request_id.
+ * Pure + deterministic given a fixed request_id; the adapters call it
+ * after extracting the request_id (so the generated-uuid path is
+ * observable/testable).
+ */
+export function mapClaimsToContext(claims, opts = {}) {
+    const actor_type = deriveActorType(claims.subjectKind);
+    const tenant_id = claims.tenantId ?? opts.tenantFallback;
+    if (!tenant_id) {
+        throw new Error("Cannot set NodiiContext: no tenant_id in claims and no tenantFallback. " +
+            "RLS + every signal key off tenant_id, so a tenant-less context is unsafe.");
+    }
+    // request_id: read x-request-id, generate a uuidv7 when absent.
+    const request_id = opts.requestId && opts.requestId.length > 0 ? opts.requestId : uuidv7();
+    const role = collapseRolesToHighest(claims.roles, opts.rolePrivilegeOrder, opts.roleFallback);
+    return {
+        tenant_id,
+        // user_id is null unless actor_type === 'user' (type invariant).
+        user_id: actor_type === "user" ? (claims.subjectId ?? null) : null,
+        actor_type,
+        on_behalf_of: claims.onBehalfOf ?? null,
+        role,
+        request_id,
+        intent_id: claims.intentId ?? null,
+    };
+}
+//# sourceMappingURL=claims.js.map

package/dist/context-adapter/claims.js.map

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

package/dist/context-adapter/grpc.d.ts

@@ -0,0 +1,62 @@
+import { type AdapterClaims, type MapClaimsOptions } from "./claims.js";
+/** Canonical inbound request-id metadata key. */
+export declare const REQUEST_ID_METADATA = "x-request-id";
+/**
+ * Minimal structural shape of a gRPC unary call this adapter reads. A
+ * real `@grpc/grpc-js` `ServerUnaryCall` (and the `@nodii/grpc-auth`
+ * `withAuthUnary` augmentation) is assignable to it; so is a synthetic
+ * test fixture. Telemetry is a foundation lib, so it declares this
+ * locally instead of importing `@nodii/grpc-interceptors` (no cycle).
+ */
+export interface GrpcUnaryCall {
+    metadata?: {
+        get(key: string): readonly unknown[] | undefined;
+    };
+    /** Attached by the upstream auth interceptor (`@nodii/grpc-auth`). */
+    auth?: {
+        serviceActor?: {
+            service_id?: string;
+            serviceId?: string;
+            tenant_id?: string;
+        } | null;
+        userActor?: {
+            user_id?: string;
+            tenant_id?: string;
+            user_role?: string;
+        } | null;
+        requestContext?: {
+            tenant_id?: string;
+            intent_id?: string;
+            actor_type?: string;
+        } | null;
+    } | null;
+    request?: unknown;
+}
+export type GrpcUnaryHandler = (call: GrpcUnaryCall) => Promise<unknown>;
+export type GrpcUnaryInterceptor = (methodName: string, handler: GrpcUnaryHandler) => GrpcUnaryHandler;
+export interface NodiiContextInterceptorOptions extends Pick<MapClaimsOptions, "rolePrivilegeOrder" | "roleFallback" | "tenantFallback"> {
+    /**
+     * Read the verified claims off the call. Defaults to reading the
+     * `call.auth` envelope (userActor / serviceActor / requestContext) the
+     * `@nodii/grpc-auth` interceptor attaches, plus the `x-user-roles`
+     * metadata when present. Override to read a custom envelope.
+     */
+    extractClaims?: (call: GrpcUnaryCall) => AdapterClaims | null;
+    /** Metadata key for the inbound request id. Defaults to `x-request-id`. */
+    requestIdMetadata?: string;
+    /**
+     * Metadata key carrying a comma-separated roles list. Defaults to
+     * `x-user-roles`. Lets the gRPC seam receive `roles[]` (the
+     * `UserActorEnvelope` only carries a single `user_role`).
+     */
+    rolesMetadata?: string;
+}
+/**
+ * gRPC server interceptor that SETS the active `NodiiContext` for the
+ * handler scope. Composes as a `(methodName, handler) => handler` wrapper
+ * (the `@nodii/grpc-interceptors` convention) and runs the wrapped
+ * handler inside `withContext` so every read of `getContext()` inside the
+ * handler — and any async work it awaits — sees the mapped context.
+ */
+export declare function nodiiContextInterceptor(options?: NodiiContextInterceptorOptions): GrpcUnaryInterceptor;
+//# sourceMappingURL=grpc.d.ts.map

package/dist/context-adapter/grpc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grpc.d.ts","sourceRoot":"","sources":["../../src/context-adapter/grpc.ts"],"names":[],"mappings":"AAgBA,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,gBAAgB,EAEtB,MAAM,aAAa,CAAC;AAErB,iDAAiD;AACjD,eAAO,MAAM,mBAAmB,iBAAiB,CAAC;AAElD;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE;QACT,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,OAAO,EAAE,GAAG,SAAS,CAAC;KAClD,CAAC;IACF,sEAAsE;IACtE,IAAI,CAAC,EAAE;QACL,YAAY,CAAC,EAAE;YACb,UAAU,CAAC,EAAE,MAAM,CAAC;YACpB,SAAS,CAAC,EAAE,MAAM,CAAC;YACnB,SAAS,CAAC,EAAE,MAAM,CAAC;SACpB,GAAG,IAAI,CAAC;QACT,SAAS,CAAC,EAAE;YACV,OAAO,CAAC,EAAE,MAAM,CAAC;YACjB,SAAS,CAAC,EAAE,MAAM,CAAC;YACnB,SAAS,CAAC,EAAE,MAAM,CAAC;SACpB,GAAG,IAAI,CAAC;QACT,cAAc,CAAC,EAAE;YACf,SAAS,CAAC,EAAE,MAAM,CAAC;YACnB,SAAS,CAAC,EAAE,MAAM,CAAC;YACnB,UAAU,CAAC,EAAE,MAAM,CAAC;SACrB,GAAG,IAAI,CAAC;KACV,GAAG,IAAI,CAAC;IACT,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,MAAM,gBAAgB,GAAG,CAAC,IAAI,EAAE,aAAa,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AACzE,MAAM,MAAM,oBAAoB,GAAG,CACjC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,gBAAgB,KACtB,gBAAgB,CAAC;AAEtB,MAAM,WAAW,8BACf,SAAQ,IAAI,CACV,gBAAgB,EAChB,oBAAoB,GAAG,cAAc,GAAG,gBAAgB,CACzD;IACD;;;;;OAKG;IACH,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,aAAa,GAAG,IAAI,CAAC;IAC9D,2EAA2E;IAC3E,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AA4ED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,GAAE,8BAAmC,GAC3C,oBAAoB,CAsBtB"}

package/dist/context-adapter/grpc.js

@@ -0,0 +1,113 @@
+// `@nodii/telemetry/context` — gRPC server entry-seam adapter (D44 § 6.5,
+// D405).
+//
+// A handler-wrapping unary interceptor `(methodName, handler) => handler`
+// (the `@nodii/grpc-auth` / `@nodii/grpc-interceptors` server-interceptor
+// convention — `@grpc/grpc-js` has no native server-interceptor API, so
+// services compose handler wrappers). It reads inbound metadata + the
+// `call.auth` envelope attached by the auth interceptor and runs the
+// handler inside a `withContext` scope so `getContext()` resolves the
+// per-request `NodiiContext` for the whole handler.
+//
+// It is an INBOUND seam: it SETS context for the handler scope and makes
+// no outbound peer calls.
+import { withContext } from "../context.js";
+import { mapClaimsToContext, } from "./claims.js";
+/** Canonical inbound request-id metadata key. */
+export const REQUEST_ID_METADATA = "x-request-id";
+/** Read the first value of a metadata key as a UTF-8 string. */
+function readMetadata(call, key) {
+    const values = call.metadata?.get(key);
+    if (!values || values.length === 0)
+        return undefined;
+    const first = values[0];
+    if (typeof first === "string")
+        return first;
+    if (first instanceof Uint8Array || Buffer.isBuffer?.(first)) {
+        try {
+            return Buffer.from(first).toString("utf8");
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+}
+/**
+ * Default claim extractor for the gRPC seam. Prefers the user actor
+ * (interactive principal) over the service actor (S2S caller). Reads
+ * `roles[]` from `x-user-roles` metadata when present, else falls back to
+ * the single `userActor.user_role`.
+ */
+function defaultExtractClaims(call, rolesMetadata) {
+    const auth = call.auth ?? null;
+    const userActor = auth?.userActor ?? null;
+    const serviceActor = auth?.serviceActor ?? null;
+    const requestContext = auth?.requestContext ?? null;
+    if (!userActor && !serviceActor && !requestContext)
+        return null;
+    // roles[]: prefer explicit metadata, else lift the singular user_role.
+    const rolesRaw = readMetadata(call, rolesMetadata);
+    const roles = rolesRaw
+        ? rolesRaw
+            .split(",")
+            .map((r) => r.trim())
+            .filter((r) => r.length > 0)
+        : userActor?.user_role
+            ? [userActor.user_role]
+            : null;
+    // Delegation (on_behalf_of / act / obo): the gRPC seam carries it in the
+    // `x-on-behalf-of` metadata header (symmetric with the Python + Go gRPC
+    // adapters). Honoured for BOTH branches — agent-delegation must NOT be
+    // silently dropped on the gRPC seam the way it is honoured on Hono.
+    const onBehalfOf = readMetadata(call, "x-on-behalf-of") ?? null;
+    if (userActor) {
+        return {
+            tenantId: userActor.tenant_id ?? requestContext?.tenant_id ?? null,
+            subjectId: userActor.user_id ?? null,
+            // Honour the auth interceptor's actor_type when it stamped one
+            // (e.g. 'agent' for a delegated principal); default to 'user' for
+            // a plain user-actor envelope. deriveActorType maps the value.
+            subjectKind: requestContext?.actor_type ?? "user",
+            roles,
+            onBehalfOf,
+            intentId: requestContext?.intent_id ?? null,
+        };
+    }
+    // S2S-only call: a service principal acting with no user actor.
+    return {
+        tenantId: serviceActor?.tenant_id ?? requestContext?.tenant_id ?? null,
+        subjectId: serviceActor?.serviceId ?? serviceActor?.service_id ?? null,
+        subjectKind: requestContext?.actor_type ?? "service",
+        roles,
+        onBehalfOf,
+        intentId: requestContext?.intent_id ?? null,
+    };
+}
+/**
+ * gRPC server interceptor that SETS the active `NodiiContext` for the
+ * handler scope. Composes as a `(methodName, handler) => handler` wrapper
+ * (the `@nodii/grpc-interceptors` convention) and runs the wrapped
+ * handler inside `withContext` so every read of `getContext()` inside the
+ * handler — and any async work it awaits — sees the mapped context.
+ */
+export function nodiiContextInterceptor(options = {}) {
+    const requestIdMetadata = options.requestIdMetadata ?? REQUEST_ID_METADATA;
+    const rolesMetadata = options.rolesMetadata ?? "x-user-roles";
+    const extract = options.extractClaims ??
+        ((call) => defaultExtractClaims(call, rolesMetadata));
+    return (_methodName, handler) => {
+        return (call) => {
+            const claims = extract(call) ?? {};
+            const requestId = readMetadata(call, requestIdMetadata) ?? null;
+            const ctx = mapClaimsToContext(claims, {
+                requestId,
+                rolePrivilegeOrder: options.rolePrivilegeOrder,
+                roleFallback: options.roleFallback,
+                tenantFallback: options.tenantFallback,
+            });
+            return withContext(ctx, () => handler(call));
+        };
+    };
+}
+//# sourceMappingURL=grpc.js.map

package/dist/context-adapter/grpc.js.map

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

package/dist/context-adapter/hono.d.ts

@@ -0,0 +1,39 @@
+import type { Context, MiddlewareHandler } from "hono";
+import { type AdapterClaims, type MapClaimsOptions } from "./claims.js";
+/** Canonical inbound request-id header (lower-case; Hono headers are case-insensitive). */
+export declare const REQUEST_ID_HEADER = "x-request-id";
+export interface NodiiContextMiddlewareOptions extends Pick<MapClaimsOptions, "rolePrivilegeOrder" | "roleFallback" | "tenantFallback"> {
+    /**
+     * Where to read the verified claims from the Hono context. Defaults to
+     * reading `c.get("nodiiClaims")` (the `@nodii/auth-sdk/hono` convention)
+     * and adapting it. Override when claims live under a different key or in
+     * a different shape.
+     */
+    extractClaims?: (c: Context) => AdapterClaims | null;
+    /**
+     * Header to read the inbound request id from. Defaults to
+     * `x-request-id`. When the header is absent a uuidv7 is generated.
+     */
+    requestIdHeader?: string;
+}
+/**
+ * Hono middleware that SETS the active `NodiiContext` for the downstream
+ * request scope. Reads verified claims (default: `c.get("nodiiClaims")`)
+ * + the `x-request-id` header, applies the locked field mappings, and
+ * runs the rest of the request inside a `withContext` scope.
+ *
+ * The context is SCOPED to the single request via `withContext` (which
+ * unwinds the AsyncLocalStorage frame when `next()` settles) — NOT a bare
+ * `setContextForCurrentScope`. A bare `enterWith` mutates the current ALS
+ * frame and never unwinds, so if the middleware is mounted at the app root
+ * (no per-request ALS frame opened first) request N's context would bleed
+ * into request N+1. `withContext` is symmetric with the gRPC interceptor
+ * and guarantees `getContext()` is unset again once the request settles.
+ *
+ * A tenant-less request (no `tenant_id` claim + no `tenantFallback`) is
+ * rejected with `400 missing_tenant_context` — a context with no tenant is
+ * unsafe to run a handler under (RLS + every signal key off `tenant_id`).
+ * Symmetric with the Go HTTP middleware (`400`) and the Python adapter.
+ */
+export declare function nodiiContextMiddleware(options?: NodiiContextMiddlewareOptions): MiddlewareHandler;
+//# sourceMappingURL=hono.d.ts.map

package/dist/context-adapter/hono.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hono.d.ts","sourceRoot":"","sources":["../../src/context-adapter/hono.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAGvD,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,gBAAgB,EAEtB,MAAM,aAAa,CAAC;AAErB,2FAA2F;AAC3F,eAAO,MAAM,iBAAiB,iBAAiB,CAAC;AAEhD,MAAM,WAAW,6BACf,SAAQ,IAAI,CACV,gBAAgB,EAChB,oBAAoB,GAAG,cAAc,GAAG,gBAAgB,CACzD;IACD;;;;;OAKG;IACH,aAAa,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,aAAa,GAAG,IAAI,CAAC;IACrD;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AA6CD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,GAAE,6BAAkC,GAC1C,iBAAiB,CA6BnB"}

package/dist/context-adapter/hono.js

@@ -0,0 +1,86 @@
+// `@nodii/telemetry/context` — Hono entry-seam adapter (D44 § 6.5, D405).
+//
+// The Hono middleware that SETS the per-request `NodiiContext` on entry.
+// Place it AFTER auth (so `c.get("nodiiClaims")` is populated) and before
+// any handler that reads `getContext()`:
+//
+//   import { requireAuth } from "@nodii/auth-sdk/hono";
+//   import { nodiiContextMiddleware } from "@nodii/telemetry/context";
+//
+//   app.use("/api/*", requireAuth({ verifier }));
+//   app.use("/api/*", nodiiContextMiddleware());
+//   app.get("/api/me", (c) => c.json(getContext()));
+//
+// It is an INBOUND seam: it sets context for the downstream scope and
+// makes no outbound peer calls.
+import { withContext } from "../context.js";
+import { mapClaimsToContext, } from "./claims.js";
+/** Canonical inbound request-id header (lower-case; Hono headers are case-insensitive). */
+export const REQUEST_ID_HEADER = "x-request-id";
+/**
+ * Default claim extractor: reads `c.get("nodiiClaims")` and maps the
+ * auth-sdk NodiiClaims surface onto `AdapterClaims`. Returns null when no
+ * claims are present (unauthenticated route) — the middleware then sets a
+ * minimal context from headers + the tenantFallback so downstream code
+ * still has a request_id-bearing context.
+ */
+function defaultExtractClaims(c) {
+    // `c.get` is typed against the app Env; cast through unknown so this
+    // adapter works regardless of the consumer's declared Variables.
+    const raw = c.get("nodiiClaims");
+    if (!raw)
+        return null;
+    return {
+        tenantId: raw.tenantId ?? null,
+        subjectId: raw.sub ?? null,
+        subjectKind: raw.principalKind ?? null,
+        roles: raw.roles ?? null,
+        onBehalfOf: raw.onBehalfOf ?? raw.impersonator?.sub ?? null,
+        intentId: raw.intentId ?? null,
+    };
+}
+/**
+ * Hono middleware that SETS the active `NodiiContext` for the downstream
+ * request scope. Reads verified claims (default: `c.get("nodiiClaims")`)
+ * + the `x-request-id` header, applies the locked field mappings, and
+ * runs the rest of the request inside a `withContext` scope.
+ *
+ * The context is SCOPED to the single request via `withContext` (which
+ * unwinds the AsyncLocalStorage frame when `next()` settles) — NOT a bare
+ * `setContextForCurrentScope`. A bare `enterWith` mutates the current ALS
+ * frame and never unwinds, so if the middleware is mounted at the app root
+ * (no per-request ALS frame opened first) request N's context would bleed
+ * into request N+1. `withContext` is symmetric with the gRPC interceptor
+ * and guarantees `getContext()` is unset again once the request settles.
+ *
+ * A tenant-less request (no `tenant_id` claim + no `tenantFallback`) is
+ * rejected with `400 missing_tenant_context` — a context with no tenant is
+ * unsafe to run a handler under (RLS + every signal key off `tenant_id`).
+ * Symmetric with the Go HTTP middleware (`400`) and the Python adapter.
+ */
+export function nodiiContextMiddleware(options = {}) {
+    const extract = options.extractClaims ?? defaultExtractClaims;
+    const requestIdHeader = options.requestIdHeader ?? REQUEST_ID_HEADER;
+    return async (c, next) => {
+        const claims = extract(c) ?? {};
+        const requestId = c.req.header(requestIdHeader) ?? null;
+        let ctx;
+        try {
+            ctx = mapClaimsToContext(claims, {
+                requestId,
+                rolePrivilegeOrder: options.rolePrivilegeOrder,
+                roleFallback: options.roleFallback,
+                tenantFallback: options.tenantFallback,
+            });
+        }
+        catch {
+            // The only throw from mapClaimsToContext is the tenant-less guard.
+            // Fail closed with a 400 (do NOT run the handler with no context).
+            return c.json({ error: true, code: "missing_tenant_context" }, 400);
+        }
+        // Scope the context to this request: established for the downstream
+        // scope, removed after `next()` settles.
+        return withContext(ctx, () => next());
+    };
+}
+//# sourceMappingURL=hono.js.map

package/dist/context-adapter/hono.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hono.js","sourceRoot":"","sources":["../../src/context-adapter/hono.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,EAAE;AACF,yEAAyE;AACzE,0EAA0E;AAC1E,yCAAyC;AACzC,EAAE;AACF,wDAAwD;AACxD,uEAAuE;AACvE,EAAE;AACF,kDAAkD;AAClD,iDAAiD;AACjD,qDAAqD;AACrD,EAAE;AACF,sEAAsE;AACtE,gCAAgC;AAGhC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C,OAAO,EAGL,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAErB,2FAA2F;AAC3F,MAAM,CAAC,MAAM,iBAAiB,GAAG,cAAc,CAAC;AAwChD;;;;;;GAMG;AACH,SAAS,oBAAoB,CAAC,CAAU;IACtC,qEAAqE;IACrE,iEAAiE;IACjE,MAAM,GAAG,GAAI,CAA4C,CAAC,GAAG,CAC3D,aAAa,CACiB,CAAC;IACjC,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC;IACtB,OAAO;QACL,QAAQ,EAAE,GAAG,CAAC,QAAQ,IAAI,IAAI;QAC9B,SAAS,EAAE,GAAG,CAAC,GAAG,IAAI,IAAI;QAC1B,WAAW,EAAE,GAAG,CAAC,aAAa,IAAI,IAAI;QACtC,KAAK,EAAE,GAAG,CAAC,KAAK,IAAI,IAAI;QACxB,UAAU,EAAE,GAAG,CAAC,UAAU,IAAI,GAAG,CAAC,YAAY,EAAE,GAAG,IAAI,IAAI;QAC3D,QAAQ,EAAE,GAAG,CAAC,QAAQ,IAAI,IAAI;KAC/B,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,sBAAsB,CACpC,UAAyC,EAAE;IAE3C,MAAM,OAAO,GAAG,OAAO,CAAC,aAAa,IAAI,oBAAoB,CAAC;IAC9D,MAAM,eAAe,GAAG,OAAO,CAAC,eAAe,IAAI,iBAAiB,CAAC;IAErE,OAAO,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE;QACvB,MAAM,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAChC,MAAM,SAAS,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,eAAe,CAAC,IAAI,IAAI,CAAC;QAExD,IAAI,GAAiB,CAAC;QACtB,IAAI,CAAC;YACH,GAAG,GAAG,kBAAkB,CAAC,MAAM,EAAE;gBAC/B,SAAS;gBACT,kBAAkB,EAAE,OAAO,CAAC,kBAAkB;gBAC9C,YAAY,EAAE,OAAO,CAAC,YAAY;gBAClC,cAAc,EAAE,OAAO,CAAC,cAAc;aACvC,CAAC,CAAC;QACL,CAAC;QAAC,MAAM,CAAC;YACP,mEAAmE;YACnE,mEAAmE;YACnE,OAAO,CAAC,CAAC,IAAI,CACX,EAAE,KAAK,EAAE,IAAa,EAAE,IAAI,EAAE,wBAAwB,EAAE,EACxD,GAAG,CACJ,CAAC;QACJ,CAAC;QAED,oEAAoE;QACpE,yCAAyC;QACzC,OAAO,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC;IACxC,CAAC,CAAC;AACJ,CAAC"}

package/dist/context-adapter/index.d.ts

@@ -0,0 +1,4 @@
+export { type AdapterClaims, type MapClaimsOptions, collapseRolesToHighest, deriveActorType, mapClaimsToContext, ROLE_PRIVILEGE_ORDER, } from "./claims.js";
+export { type NodiiContextMiddlewareOptions, nodiiContextMiddleware, REQUEST_ID_HEADER, } from "./hono.js";
+export { type GrpcUnaryCall, type GrpcUnaryHandler, type GrpcUnaryInterceptor, type NodiiContextInterceptorOptions, nodiiContextInterceptor, REQUEST_ID_METADATA, } from "./grpc.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/context-adapter/index.ts"],"names":[],"mappings":"AAcA,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,sBAAsB,EACtB,eAAe,EACf,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,KAAK,6BAA6B,EAClC,sBAAsB,EACtB,iBAAiB,GAClB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,8BAA8B,EACnC,uBAAuB,EACvB,mBAAmB,GACpB,MAAM,WAAW,CAAC"}

package/dist/context-adapter/index.js

@@ -0,0 +1,17 @@
+// `@nodii/telemetry/context` — entry-seam context adapters (D44 § 6.5,
+// D405 context adoption; req b3b03fc5 / clarification c9906a51).
+//
+// These adapters SET the per-request `NodiiContext` at the entry seam:
+//   - `nodiiContextMiddleware` — Hono middleware (HTTP entry).
+//   - `nodiiContextInterceptor` — gRPC unary server interceptor.
+//
+// Both apply the operator-LOCKED field mappings (see `claims.ts`):
+//   actor_type ← subject kind; role ← highest-privilege of roles[];
+//   on_behalf_of ← delegation claim; request_id ← x-request-id || uuidv7().
+//
+// Lives behind a subpath so consumers who don't run an HTTP/gRPC entry
+// seam (cron / sweeper flows) don't pull `hono`.
+export { collapseRolesToHighest, deriveActorType, mapClaimsToContext, ROLE_PRIVILEGE_ORDER, } from "./claims.js";
+export { nodiiContextMiddleware, REQUEST_ID_HEADER, } from "./hono.js";
+export { nodiiContextInterceptor, REQUEST_ID_METADATA, } from "./grpc.js";
+//# sourceMappingURL=index.js.map

package/dist/context-adapter/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/context-adapter/index.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,iEAAiE;AACjE,EAAE;AACF,uEAAuE;AACvE,+DAA+D;AAC/D,iEAAiE;AACjE,EAAE;AACF,mEAAmE;AACnE,oEAAoE;AACpE,4EAA4E;AAC5E,EAAE;AACF,uEAAuE;AACvE,iDAAiD;AAEjD,OAAO,EAGL,sBAAsB,EACtB,eAAe,EACf,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,aAAa,CAAC;AACrB,OAAO,EAEL,sBAAsB,EACtB,iBAAiB,GAClB,MAAM,WAAW,CAAC;AACnB,OAAO,EAKL,uBAAuB,EACvB,mBAAmB,GACpB,MAAM,WAAW,CAAC"}

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EACL,UAAU,EACV,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC9E,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,MAAM,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACxE,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,YAAY,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,YAAY,EACV,oBAAoB,EACpB,IAAI,EACJ,QAAQ,EACR,WAAW,EACX,UAAU,EACV,UAAU,EACV,UAAU,GACX,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,OAAO,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5E,YAAY,EACV,aAAa,EACb,WAAW,EACX,eAAe,EACf,UAAU,EACV,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,wBAAwB,EACxB,gCAAgC,EAChC,yBAAyB,EACzB,cAAc,EACd,eAAe,EACf,8BAA8B,EAC9B,KAAK,EACL,iBAAiB,EACjB,cAAc,GACf,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,SAAS,EACT,UAAU,EACV,SAAS,EACT,iBAAiB,EACjB,UAAU,EACV,aAAa,EACb,YAAY,EACZ,WAAW,EACX,0BAA0B,GAC3B,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,2BAA2B,EAAE,MAAM,YAAY,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,YAAY,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC;AAChE,OAAO,EAAE,MAAM,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,UAAU,EACV,cAAc,EACd,WAAW,GACZ,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,eAAe,GAChB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AACrD,YAAY,EACV,SAAS,EACT,sBAAsB,EACtB,oBAAoB,EACpB,yBAAyB,EACzB,kBAAkB,EAClB,uBAAuB,EACvB,wBAAwB,EACxB,yBAAyB,EACzB,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,EAClB,WAAW,EACX,QAAQ,EACR,YAAY,EACZ,qBAAqB,EACrB,wBAAwB,EACxB,YAAY,EACZ,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EAClB,cAAc,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,uBAAuB,EACvB,eAAe,EACf,4BAA4B,EAC5B,2BAA2B,GAC5B,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAwBA,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EACL,UAAU,EACV,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC9E,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,MAAM,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACxE,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,YAAY,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,YAAY,EACV,oBAAoB,EACpB,IAAI,EACJ,QAAQ,EACR,WAAW,EACX,UAAU,EACV,UAAU,EACV,UAAU,GACX,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,OAAO,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5E,YAAY,EACV,aAAa,EACb,WAAW,EACX,eAAe,EACf,UAAU,EACV,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,wBAAwB,EACxB,gCAAgC,EAChC,yBAAyB,EACzB,cAAc,EACd,eAAe,EACf,8BAA8B,EAC9B,KAAK,EACL,iBAAiB,EACjB,cAAc,GACf,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,SAAS,EACT,UAAU,EACV,SAAS,EACT,iBAAiB,EACjB,UAAU,EACV,aAAa,EACb,YAAY,EACZ,WAAW,EACX,0BAA0B,GAC3B,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,2BAA2B,EAAE,MAAM,YAAY,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,YAAY,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC;AAChE,OAAO,EAAE,MAAM,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,UAAU,EACV,cAAc,EACd,WAAW,GACZ,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,eAAe,GAChB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AACrD,YAAY,EACV,SAAS,EACT,sBAAsB,EACtB,oBAAoB,EACpB,yBAAyB,EACzB,kBAAkB,EAClB,uBAAuB,EACvB,wBAAwB,EACxB,yBAAyB,EACzB,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,EAClB,WAAW,EACX,QAAQ,EACR,YAAY,EACZ,qBAAqB,EACrB,wBAAwB,EACxB,YAAY,EACZ,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EAClB,cAAc,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,uBAAuB,EACvB,eAAe,EACf,4BAA4B,EAC5B,2BAA2B,GAC5B,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -2,12 +2,18 @@
 //
 // Spec: planning hub feature_doc serviceId=nodii-libs docKey=telemetry v3
 //
-// Use subpath imports for tree-shaking:
-//   - @nodii/telemetry/grpc            — gRPC interceptor + client wrapper
-//   - @nodii/telemetry/bullmq          — BullMQ producer + consumer wrappers
-//   - @nodii/telemetry/outbox          — Outbox emit + drainer instrumentation
-//   - @nodii/telemetry/system-process  — System-process adapter
-//   - @nodii/telemetry/lambda          — Lambda lifecycle wrapper
+// Subpath imports (the entry-seam adapters per D44 § 6.5 / D405). Each is
+// a real, built, exported subpath — verified by the subpath-import test:
+//   - @nodii/telemetry/context  — Hono middleware + gRPC server interceptor
+//                                 that SET NodiiContext at the entry seam.
+//   - @nodii/telemetry/outbox   — Outbox emit + propagation-column adapter.
+//   - @nodii/telemetry/drizzle  — Drizzle audit_event schema fragments.
+//
+// Not yet shipped (D44 § 6.5 lists them; no implementation exists yet —
+// they are tracked as follow-on requests, NOT advertised as vapor):
+//   - bullmq          (BullMQ producer/consumer context envelope, D42)
+//   - system-process  (cron/sweeper synthetic context, § 6.6)
+//   - saga            (saga-step context coupling)
 //
 // Top-level barrel re-exports the public surface so the common-case
 // import works:

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,oCAAoC;AACpC,EAAE;AACF,0EAA0E;AAC1E,EAAE;AACF,wCAAwC;AACxC,2EAA2E;AAC3E,6EAA6E;AAC7E,+EAA+E;AAC/E,gEAAgE;AAChE,kEAAkE;AAClE,EAAE;AACF,oEAAoE;AACpE,gBAAgB;AAChB,EAAE;AACF,oEAAoE;AACpE,gEAAgE;AAChE,0DAA0D;AAE1D,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EACL,UAAU,EACV,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,MAAM,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACxE,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAWjD,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,OAAO,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAS5E,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,wBAAwB,EACxB,gCAAgC,EAChC,yBAAyB,EACzB,cAAc,EACd,eAAe,EACf,8BAA8B,EAC9B,KAAK,EACL,iBAAiB,EACjB,cAAc,GACf,MAAM,YAAY,CAAC;AAYpB,OAAO,EAAE,2BAA2B,EAAE,MAAM,YAAY,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAEpD,OAAO,EAAE,MAAM,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,UAAU,EACV,cAAc,EACd,WAAW,GACZ,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,eAAe,GAChB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AA0BrD,OAAO,EACL,uBAAuB,EACvB,eAAe,EACf,4BAA4B,EAC5B,2BAA2B,GAC5B,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,oCAAoC;AACpC,EAAE;AACF,0EAA0E;AAC1E,EAAE;AACF,0EAA0E;AAC1E,yEAAyE;AACzE,4EAA4E;AAC5E,2EAA2E;AAC3E,4EAA4E;AAC5E,wEAAwE;AACxE,EAAE;AACF,wEAAwE;AACxE,oEAAoE;AACpE,uEAAuE;AACvE,8DAA8D;AAC9D,mDAAmD;AACnD,EAAE;AACF,oEAAoE;AACpE,gBAAgB;AAChB,EAAE;AACF,oEAAoE;AACpE,gEAAgE;AAChE,0DAA0D;AAE1D,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EACL,UAAU,EACV,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,MAAM,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACxE,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAWjD,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,OAAO,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAS5E,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,wBAAwB,EACxB,gCAAgC,EAChC,yBAAyB,EACzB,cAAc,EACd,eAAe,EACf,8BAA8B,EAC9B,KAAK,EACL,iBAAiB,EACjB,cAAc,GACf,MAAM,YAAY,CAAC;AAYpB,OAAO,EAAE,2BAA2B,EAAE,MAAM,YAAY,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAEpD,OAAO,EAAE,MAAM,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,UAAU,EACV,cAAc,EACd,WAAW,GACZ,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,eAAe,GAChB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AA0BrD,OAAO,EACL,uBAAuB,EACvB,eAAe,EACf,4BAA4B,EAC5B,2BAA2B,GAC5B,MAAM,YAAY,CAAC"}

package/dist/outbox/index.d.ts

@@ -0,0 +1,2 @@
+export { type OutboxColumns, type OutboxEvent, type OutboxWriter, _resetOutboxWriterForTests, _setOutboxWriter, emitOutbox, } from "../outbox-emit.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/outbox/index.ts"],"names":[],"mappings":"AAYA,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,0BAA0B,EAC1B,gBAAgB,EAChB,UAAU,GACX,MAAM,mBAAmB,CAAC"}

package/dist/outbox/index.js

@@ -0,0 +1,13 @@
+// `@nodii/telemetry/outbox` — Outbox emit + propagation-column adapter
+// (D43, communication-doctrine § 9.1).
+//
+// `emitOutbox(event)` stages an outbox row deriving the propagation
+// columns (`tenant_id, request_id, intent_id, trace_parent, trace_state`)
+// + `context_envelope` jsonb from the active `NodiiContext` + OTel span.
+// `_setOutboxWriter` lets service init wire the per-service writer that
+// persists the row inside the service's transaction.
+//
+// Lives behind a subpath so consumers who don't emit outbox rows don't
+// load the helper.
+export { _resetOutboxWriterForTests, _setOutboxWriter, emitOutbox, } from "../outbox-emit.js";
+//# sourceMappingURL=index.js.map

package/dist/outbox/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/outbox/index.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,uCAAuC;AACvC,EAAE;AACF,oEAAoE;AACpE,0EAA0E;AAC1E,yEAAyE;AACzE,wEAAwE;AACxE,qDAAqD;AACrD,EAAE;AACF,uEAAuE;AACvE,mBAAmB;AAEnB,OAAO,EAIL,0BAA0B,EAC1B,gBAAgB,EAChB,UAAU,GACX,MAAM,mBAAmB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodii/telemetry",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Substrate observability library for the Nodii microservice stack — OTel wrapper, log envelope, intent lifecycle, audit signal, agent registry, context propagation. Spec: planning hub docKey=telemetry.",
   "license": "MIT",
   "type": "module",
@@ -14,6 +14,14 @@
     "./drizzle": {
       "types": "./dist/drizzle/index.d.ts",
       "default": "./dist/drizzle/index.js"
+    },
+    "./context": {
+      "types": "./dist/context-adapter/index.d.ts",
+      "default": "./dist/context-adapter/index.js"
+    },
+    "./outbox": {
+      "types": "./dist/outbox/index.d.ts",
+      "default": "./dist/outbox/index.js"
     }
   },
   "files": [
@@ -47,10 +55,11 @@
     "@opentelemetry/semantic-conventions": "^1.28.0"
   },
   "peerDependencies": {
-    "@nodii/audit-chain": "^0.9.1",
+    "@nodii/audit-chain": ">=0.9.1 <1.0.0",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/api-logs": "^0.57.2",
-    "drizzle-orm": ">=0.36 <0.50"
+    "drizzle-orm": ">=0.36 <0.50",
+    "hono": "^4.0.0"
   },
   "peerDependenciesMeta": {
     "@nodii/audit-chain": {
@@ -64,11 +73,15 @@
     },
     "drizzle-orm": {
       "optional": true
+    },
+    "hono": {
+      "optional": true
     }
   },
   "devDependencies": {
-    "@nodii/audit-chain": "0.9.1",
+    "@nodii/audit-chain": "0.10.0",
     "drizzle-orm": "^0.45.2",
+    "hono": "^4.4.0",
     "postgres": "^3.4.0",
     "typescript": "^5.9.3"
   },