ccqa-tools 1.37.0

package/dist/coverage/core.d.cts

@@ -0,0 +1,157 @@
+//#region src/coverage/core.d.ts
+/**
+ * The hot path, and the only module instrumented application code imports.
+ *
+ * It has **no imports at all**, on purpose. Bundlers pull this file into every
+ * layer they build — a Next.js RSC bundle, an SSR bundle, a route-handler
+ * bundle, a Temporal workflow sandbox — and each of those rejects a different
+ * subset of Node built-ins. `node:http` alone is enough to fail a Next.js
+ * webpack build outright. Everything platform-specific lives behind
+ * `ccqa-tools/coverage/register`, which only ever loads in real Node.
+ *
+ * For the same reason the process-wide state hangs off `globalThis` rather than
+ * module scope: a bundler produces several copies of this file per process, and
+ * a per-copy AsyncLocalStorage would shard attribution across them.
+ */
+/** The slice of AsyncLocalStorage this package needs, minus the import. */
+interface ContextStorage<T> {
+  getStore(): T | undefined;
+  run<R>(store: T, fn: () => R): R;
+}
+/**
+ * What one in-flight execution carries.
+ *
+ * Exactly one of the two says where its reach goes. `specId` is set when the
+ * request itself named a spec. `actor` is set when nothing did, and all that is
+ * known is who caused the work and when it was first asked for — enough for the
+ * run to decide later, and nothing this process could decide on its own.
+ */
+interface CoverageStore {
+  specId?: string;
+  actor?: ActorMark;
+  files: Set<string>;
+}
+/** Who caused a request, and the instant it arrived. Never interpreted here. */
+interface ActorMark {
+  tag: string;
+  at: number;
+}
+/** One identity's reach from one instant, as the collector ships it. */
+interface ActorBucket {
+  tag: string;
+  at: number;
+  files: Set<string>;
+}
+interface CoverageRuntime {
+  /**
+   * Shape version of this object. Two builds of `ccqa-tools` can end up in
+   * one process (an app dependency and a hoisted transitive one); the first to
+   * install wins and the rest defer to it, so the shape has to be recognisable.
+   */
+  readonly protocol: 1;
+  readonly als: ContextStorage<CoverageStore>;
+  /** specId -> reached file ids. Union is idempotent, so merging is free. */
+  readonly buckets: Map<string, Set<string>>;
+  /**
+   * `<tag> <at>` -> what that identity reached from that instant.
+   *
+   * Kept apart from `buckets` because nothing here knows which spec they belong
+   * to — or whether they belong to one at all. Most of them are other people
+   * using the same environment, and the run discards those.
+   */
+  readonly actors: Map<string, ActorBucket>;
+  /**
+   * Files reached at module top level. Kept out of the spec buckets because the
+   * first spec to import a module would otherwise own it, making the result
+   * depend on spec execution order.
+   */
+  readonly boot: Set<string>;
+  /**
+   * Number of open buckets, spec and identity alike. `record()` returns on zero
+   * before touching anything else — the reason instrumentation costs nothing
+   * while nothing is being measured, and the reason this package does not need
+   * sampling. A field rather than a `.size` sum because this check is the hot
+   * path itself.
+   *
+   * An identity bucket arms it the same way a spec does, so an application with
+   * the actor preset installed pays while any identity has acted recently, not
+   * only while a spec is running. That is the price of the application not
+   * being told which identities matter.
+   */
+  active: number;
+  /**
+   * Executions that ran while a spec was open but outside its async context.
+   * A silent gap here would read as "never reached", so it is always counted.
+   */
+  unattributed: number;
+  /**
+   * Files a load hook saw but could not turn into recorded coverage — an
+   * undecodable source, or a parse error. Uncounted, this would render
+   * identically to "reached by no spec", which is a lie.
+   */
+  uninstrumentedFiles: number;
+  /**
+   * Set when nothing in this process can be instrumented at all, so every file
+   * it runs is missing rather than some of them.
+   *
+   * A flag and not a count, because the failure is the process: counted as one
+   * file it reads as a rounding error next to the thousands it actually hides.
+   */
+  uninstrumentedProcess: boolean;
+  readonly pid: number;
+  readonly startedAt: number;
+}
+/** The name instrumented code calls through. Kept short; it appears per module. */
+declare const GLOBAL_RECORD = "__ccqaCoverage";
+declare function getRuntime(): CoverageRuntime | undefined;
+/**
+ * Installs the process-wide runtime, or returns the one already there.
+ * Called by `ccqa-tools/coverage/register`; application code never calls it.
+ */
+declare function installRuntime(als: ContextStorage<CoverageStore>): CoverageRuntime;
+/**
+ * Marks a file as reached. Instrumented code calls this through
+ * `globalThis.__ccqaCoverage`, so the call sites cost one global read per
+ * module and one truthiness check per invocation when coverage is off.
+ *
+ * @param topLevel set by the prologue a module runs on first import.
+ */
+declare function record(fileId: string, topLevel?: boolean): void;
+/** The spec the current async context belongs to, if any. */
+declare function currentSpecId(): string | undefined;
+/**
+ * Opens `specId`'s bucket and runs `fn` inside its context. Every entry point —
+ * HTTP, Temporal activity, manual — funnels through here.
+ *
+ * The bucket outlives `fn`: work a request schedules and does not await still
+ * belongs to the spec that caused it.
+ */
+declare function runInSpec<R>(specId: string, fn: () => R): R;
+/**
+ * Records that `tag` caused this work at `at`, without deciding whose it is.
+ *
+ * Carrier wins: a request that already named a spec needs no identity, and
+ * overwriting it would replace a fact with something the run still has to
+ * interpret. Everything else is recorded whoever it came from — the application
+ * is never told which identities are being measured, so it cannot filter, and
+ * the run discards the ones it did not ask for.
+ */
+declare function runAsActor<R>(tag: string, at: number, fn: () => R): R;
+/** The identity mark on the current async context, if it has one. */
+declare function currentActor(): ActorMark | undefined;
+/** Returns `specId`'s file set, creating it — and arming the gate — if new. */
+declare function openBucket(runtime: CoverageRuntime, specId: string): Set<string>;
+/**
+ * The key both halves of the collector agree on. A space separates them safely:
+ * a spec id can never contain one, so identity keys and spec ids stay disjoint
+ * where the collector tracks both in one map.
+ */
+declare function actorBucketKey(tag: string, at: number): string;
+/** Returns the identity's file set for that instant, creating it if new. */
+declare function openActorBucket(runtime: CoverageRuntime, tag: string, at: number): Set<string>;
+/** Drops a spec's bucket once it has been handed to the collector. */
+declare function closeBucket(runtime: CoverageRuntime, specId: string): void;
+/** Drops an identity's bucket once it has been handed to the collector. */
+declare function closeActorBucket(runtime: CoverageRuntime, key: string): void;
+//#endregion
+export { ActorBucket, ActorMark, ContextStorage, CoverageRuntime, CoverageStore, GLOBAL_RECORD, actorBucketKey, closeActorBucket, closeBucket, currentActor, currentSpecId, getRuntime, installRuntime, openActorBucket, openBucket, record, runAsActor, runInSpec };

package/dist/coverage/core.d.ts

@@ -0,0 +1,157 @@
+//#region src/coverage/core.d.ts
+/**
+ * The hot path, and the only module instrumented application code imports.
+ *
+ * It has **no imports at all**, on purpose. Bundlers pull this file into every
+ * layer they build — a Next.js RSC bundle, an SSR bundle, a route-handler
+ * bundle, a Temporal workflow sandbox — and each of those rejects a different
+ * subset of Node built-ins. `node:http` alone is enough to fail a Next.js
+ * webpack build outright. Everything platform-specific lives behind
+ * `ccqa-tools/coverage/register`, which only ever loads in real Node.
+ *
+ * For the same reason the process-wide state hangs off `globalThis` rather than
+ * module scope: a bundler produces several copies of this file per process, and
+ * a per-copy AsyncLocalStorage would shard attribution across them.
+ */
+/** The slice of AsyncLocalStorage this package needs, minus the import. */
+interface ContextStorage<T> {
+  getStore(): T | undefined;
+  run<R>(store: T, fn: () => R): R;
+}
+/**
+ * What one in-flight execution carries.
+ *
+ * Exactly one of the two says where its reach goes. `specId` is set when the
+ * request itself named a spec. `actor` is set when nothing did, and all that is
+ * known is who caused the work and when it was first asked for — enough for the
+ * run to decide later, and nothing this process could decide on its own.
+ */
+interface CoverageStore {
+  specId?: string;
+  actor?: ActorMark;
+  files: Set<string>;
+}
+/** Who caused a request, and the instant it arrived. Never interpreted here. */
+interface ActorMark {
+  tag: string;
+  at: number;
+}
+/** One identity's reach from one instant, as the collector ships it. */
+interface ActorBucket {
+  tag: string;
+  at: number;
+  files: Set<string>;
+}
+interface CoverageRuntime {
+  /**
+   * Shape version of this object. Two builds of `ccqa-tools` can end up in
+   * one process (an app dependency and a hoisted transitive one); the first to
+   * install wins and the rest defer to it, so the shape has to be recognisable.
+   */
+  readonly protocol: 1;
+  readonly als: ContextStorage<CoverageStore>;
+  /** specId -> reached file ids. Union is idempotent, so merging is free. */
+  readonly buckets: Map<string, Set<string>>;
+  /**
+   * `<tag> <at>` -> what that identity reached from that instant.
+   *
+   * Kept apart from `buckets` because nothing here knows which spec they belong
+   * to — or whether they belong to one at all. Most of them are other people
+   * using the same environment, and the run discards those.
+   */
+  readonly actors: Map<string, ActorBucket>;
+  /**
+   * Files reached at module top level. Kept out of the spec buckets because the
+   * first spec to import a module would otherwise own it, making the result
+   * depend on spec execution order.
+   */
+  readonly boot: Set<string>;
+  /**
+   * Number of open buckets, spec and identity alike. `record()` returns on zero
+   * before touching anything else — the reason instrumentation costs nothing
+   * while nothing is being measured, and the reason this package does not need
+   * sampling. A field rather than a `.size` sum because this check is the hot
+   * path itself.
+   *
+   * An identity bucket arms it the same way a spec does, so an application with
+   * the actor preset installed pays while any identity has acted recently, not
+   * only while a spec is running. That is the price of the application not
+   * being told which identities matter.
+   */
+  active: number;
+  /**
+   * Executions that ran while a spec was open but outside its async context.
+   * A silent gap here would read as "never reached", so it is always counted.
+   */
+  unattributed: number;
+  /**
+   * Files a load hook saw but could not turn into recorded coverage — an
+   * undecodable source, or a parse error. Uncounted, this would render
+   * identically to "reached by no spec", which is a lie.
+   */
+  uninstrumentedFiles: number;
+  /**
+   * Set when nothing in this process can be instrumented at all, so every file
+   * it runs is missing rather than some of them.
+   *
+   * A flag and not a count, because the failure is the process: counted as one
+   * file it reads as a rounding error next to the thousands it actually hides.
+   */
+  uninstrumentedProcess: boolean;
+  readonly pid: number;
+  readonly startedAt: number;
+}
+/** The name instrumented code calls through. Kept short; it appears per module. */
+declare const GLOBAL_RECORD = "__ccqaCoverage";
+declare function getRuntime(): CoverageRuntime | undefined;
+/**
+ * Installs the process-wide runtime, or returns the one already there.
+ * Called by `ccqa-tools/coverage/register`; application code never calls it.
+ */
+declare function installRuntime(als: ContextStorage<CoverageStore>): CoverageRuntime;
+/**
+ * Marks a file as reached. Instrumented code calls this through
+ * `globalThis.__ccqaCoverage`, so the call sites cost one global read per
+ * module and one truthiness check per invocation when coverage is off.
+ *
+ * @param topLevel set by the prologue a module runs on first import.
+ */
+declare function record(fileId: string, topLevel?: boolean): void;
+/** The spec the current async context belongs to, if any. */
+declare function currentSpecId(): string | undefined;
+/**
+ * Opens `specId`'s bucket and runs `fn` inside its context. Every entry point —
+ * HTTP, Temporal activity, manual — funnels through here.
+ *
+ * The bucket outlives `fn`: work a request schedules and does not await still
+ * belongs to the spec that caused it.
+ */
+declare function runInSpec<R>(specId: string, fn: () => R): R;
+/**
+ * Records that `tag` caused this work at `at`, without deciding whose it is.
+ *
+ * Carrier wins: a request that already named a spec needs no identity, and
+ * overwriting it would replace a fact with something the run still has to
+ * interpret. Everything else is recorded whoever it came from — the application
+ * is never told which identities are being measured, so it cannot filter, and
+ * the run discards the ones it did not ask for.
+ */
+declare function runAsActor<R>(tag: string, at: number, fn: () => R): R;
+/** The identity mark on the current async context, if it has one. */
+declare function currentActor(): ActorMark | undefined;
+/** Returns `specId`'s file set, creating it — and arming the gate — if new. */
+declare function openBucket(runtime: CoverageRuntime, specId: string): Set<string>;
+/**
+ * The key both halves of the collector agree on. A space separates them safely:
+ * a spec id can never contain one, so identity keys and spec ids stay disjoint
+ * where the collector tracks both in one map.
+ */
+declare function actorBucketKey(tag: string, at: number): string;
+/** Returns the identity's file set for that instant, creating it if new. */
+declare function openActorBucket(runtime: CoverageRuntime, tag: string, at: number): Set<string>;
+/** Drops a spec's bucket once it has been handed to the collector. */
+declare function closeBucket(runtime: CoverageRuntime, specId: string): void;
+/** Drops an identity's bucket once it has been handed to the collector. */
+declare function closeActorBucket(runtime: CoverageRuntime, key: string): void;
+//#endregion
+export { ActorBucket, ActorMark, ContextStorage, CoverageRuntime, CoverageStore, GLOBAL_RECORD, actorBucketKey, closeActorBucket, closeBucket, currentActor, currentSpecId, getRuntime, installRuntime, openActorBucket, openBucket, record, runAsActor, runInSpec };

package/dist/coverage/core.js

@@ -0,0 +1,163 @@
+//#region src/coverage/core.ts
+const RUNTIME_KEY = Symbol.for("ccqa.coverage.runtime");
+/** The name instrumented code calls through. Kept short; it appears per module. */
+const GLOBAL_RECORD = "__ccqaCoverage";
+function globals() {
+	return globalThis;
+}
+function getRuntime() {
+	return globals()[RUNTIME_KEY];
+}
+/**
+* Memoized so the hot path skips the `globalThis` read. `installRuntime`
+* primes it and never replaces an installed runtime, so once set it never
+* goes stale — but it must stay undefined (and keep re-reading `globalThis`)
+* until then, or a module that finished loading before `register` installs
+* the runtime would be stuck uninstrumented for the rest of the process.
+*/
+let cachedRuntime;
+function runtime() {
+	if (cachedRuntime === void 0) cachedRuntime = globals()[RUNTIME_KEY];
+	return cachedRuntime;
+}
+/**
+* Installs the process-wide runtime, or returns the one already there.
+* Called by `ccqa-tools/coverage/register`; application code never calls it.
+*/
+function installRuntime(als) {
+	const g = globals();
+	const existing = g[RUNTIME_KEY];
+	if (existing) {
+		cachedRuntime = existing;
+		return existing;
+	}
+	const created = {
+		protocol: 1,
+		als,
+		buckets: /* @__PURE__ */ new Map(),
+		actors: /* @__PURE__ */ new Map(),
+		boot: /* @__PURE__ */ new Set(),
+		active: 0,
+		unattributed: 0,
+		uninstrumentedFiles: 0,
+		uninstrumentedProcess: false,
+		pid: typeof process === "undefined" ? -1 : process.pid,
+		startedAt: Date.now()
+	};
+	g[RUNTIME_KEY] = created;
+	g[GLOBAL_RECORD] = record;
+	cachedRuntime = created;
+	return created;
+}
+/**
+* Marks a file as reached. Instrumented code calls this through
+* `globalThis.__ccqaCoverage`, so the call sites cost one global read per
+* module and one truthiness check per invocation when coverage is off.
+*
+* @param topLevel set by the prologue a module runs on first import.
+*/
+function record(fileId, topLevel) {
+	const rt = runtime();
+	if (rt === void 0) return;
+	if (topLevel === true) {
+		rt.boot.add(fileId);
+		return;
+	}
+	if (rt.active === 0) return;
+	const store = rt.als.getStore();
+	if (store === void 0) {
+		rt.unattributed++;
+		return;
+	}
+	store.files.add(fileId);
+}
+/** The spec the current async context belongs to, if any. */
+function currentSpecId() {
+	return runtime()?.als.getStore()?.specId;
+}
+/**
+* Opens `specId`'s bucket and runs `fn` inside its context. Every entry point —
+* HTTP, Temporal activity, manual — funnels through here.
+*
+* The bucket outlives `fn`: work a request schedules and does not await still
+* belongs to the spec that caused it.
+*/
+function runInSpec(specId, fn) {
+	const rt = runtime();
+	if (rt === void 0) return fn();
+	return rt.als.run({
+		specId,
+		files: openBucket(rt, specId)
+	}, fn);
+}
+/**
+* Records that `tag` caused this work at `at`, without deciding whose it is.
+*
+* Carrier wins: a request that already named a spec needs no identity, and
+* overwriting it would replace a fact with something the run still has to
+* interpret. Everything else is recorded whoever it came from — the application
+* is never told which identities are being measured, so it cannot filter, and
+* the run discards the ones it did not ask for.
+*/
+function runAsActor(tag, at, fn) {
+	const rt = runtime();
+	if (rt === void 0) return fn();
+	if (rt.als.getStore()?.specId !== void 0) return fn();
+	return rt.als.run({
+		actor: {
+			tag,
+			at
+		},
+		files: openActorBucket(rt, tag, at)
+	}, fn);
+}
+/** The identity mark on the current async context, if it has one. */
+function currentActor() {
+	return runtime()?.als.getStore()?.actor;
+}
+/** Returns `specId`'s file set, creating it — and arming the gate — if new. */
+function openBucket(runtime, specId) {
+	let files = runtime.buckets.get(specId);
+	if (files === void 0) {
+		files = /* @__PURE__ */ new Set();
+		runtime.buckets.set(specId, files);
+		armGate(runtime);
+	}
+	return files;
+}
+/**
+* The key both halves of the collector agree on. A space separates them safely:
+* a spec id can never contain one, so identity keys and spec ids stay disjoint
+* where the collector tracks both in one map.
+*/
+function actorBucketKey(tag, at) {
+	return `${tag} ${at}`;
+}
+/** Returns the identity's file set for that instant, creating it if new. */
+function openActorBucket(runtime, tag, at) {
+	const key = actorBucketKey(tag, at);
+	let bucket = runtime.actors.get(key);
+	if (bucket === void 0) {
+		bucket = {
+			tag,
+			at,
+			files: /* @__PURE__ */ new Set()
+		};
+		runtime.actors.set(key, bucket);
+		armGate(runtime);
+	}
+	return bucket.files;
+}
+/** Drops a spec's bucket once it has been handed to the collector. */
+function closeBucket(runtime, specId) {
+	if (runtime.buckets.delete(specId)) armGate(runtime);
+}
+/** Drops an identity's bucket once it has been handed to the collector. */
+function closeActorBucket(runtime, key) {
+	if (runtime.actors.delete(key)) armGate(runtime);
+}
+function armGate(runtime) {
+	runtime.active = runtime.buckets.size + runtime.actors.size;
+}
+//#endregion
+export { GLOBAL_RECORD, actorBucketKey, closeActorBucket, closeBucket, currentActor, currentSpecId, getRuntime, installRuntime, openActorBucket, openBucket, record, runAsActor, runInSpec };

package/dist/coverage/middleware.cjs

@@ -0,0 +1,161 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/coverage/core.ts
+const RUNTIME_KEY = Symbol.for("ccqa.coverage.runtime");
+function globals() {
+	return globalThis;
+}
+/**
+* Memoized so the hot path skips the `globalThis` read. `installRuntime`
+* primes it and never replaces an installed runtime, so once set it never
+* goes stale — but it must stay undefined (and keep re-reading `globalThis`)
+* until then, or a module that finished loading before `register` installs
+* the runtime would be stuck uninstrumented for the rest of the process.
+*/
+let cachedRuntime;
+function runtime() {
+	if (cachedRuntime === void 0) cachedRuntime = globals()[RUNTIME_KEY];
+	return cachedRuntime;
+}
+/** The spec the current async context belongs to, if any. */
+function currentSpecId() {
+	return runtime()?.als.getStore()?.specId;
+}
+/**
+* Opens `specId`'s bucket and runs `fn` inside its context. Every entry point —
+* HTTP, Temporal activity, manual — funnels through here.
+*
+* The bucket outlives `fn`: work a request schedules and does not await still
+* belongs to the spec that caused it.
+*/
+function runInSpec(specId, fn) {
+	const rt = runtime();
+	if (rt === void 0) return fn();
+	return rt.als.run({
+		specId,
+		files: openBucket(rt, specId)
+	}, fn);
+}
+/** Returns `specId`'s file set, creating it — and arming the gate — if new. */
+function openBucket(runtime, specId) {
+	let files = runtime.buckets.get(specId);
+	if (files === void 0) {
+		files = /* @__PURE__ */ new Set();
+		runtime.buckets.set(specId, files);
+		armGate(runtime);
+	}
+	return files;
+}
+function armGate(runtime) {
+	runtime.active = runtime.buckets.size + runtime.actors.size;
+}
+//#endregion
+//#region src/coverage/wire.ts
+/**
+* The names a spec id travels under. Every carrier holds the same value,
+* `<runId>.<specId>`, so a hop between them is a copy and never a translation.
+*
+* Like `core.ts` this file imports nothing: the Temporal workflow sandbox reads
+* it too.
+*/
+/** Set on the browser by ccqa at spec start, scoped to the target origin. */
+const COOKIE_NAME = "__ccqa_coverage";
+/** OTel baggage key, for the hop from the first service to downstream ones. */
+const BAGGAGE_KEY = "ccqa.coverage";
+const SPEC_ID = /^[A-Za-z0-9._\-/]{1,200}$/;
+/**
+* Accepts a carrier value only if it looks like an id we wrote.
+*
+* The cookie is client-controlled, so this is the first of two gates: the
+* second is the hub refusing runs it never started.
+*/
+function parseSpecId(raw) {
+	if (!raw) return void 0;
+	const value = raw.trim();
+	if (!SPEC_ID.test(value)) return void 0;
+	if (value === "1" || value === "true") return void 0;
+	return value;
+}
+function readCookie(header) {
+	return readKeyed(header, COOKIE_NAME, ";");
+}
+/** Pulls our key out of a `baggage` header (W3C: `k=v;props,k2=v2`). */
+function readBaggage(header) {
+	return readKeyed(header, BAGGAGE_KEY, ",", ";");
+}
+/**
+* Both carriers are `key=value` lists; they differ only in what separates the
+* entries, and baggage allowing properties after each value.
+*
+* One function because the decode-and-validate step is the part that matters,
+* and two copies of it would be free to drift into accepting different things.
+*/
+function readKeyed(header, key, between, propertiesAfter) {
+	if (!header) return void 0;
+	if (header.indexOf(key) < 0) return void 0;
+	for (const raw of header.split(between)) {
+		const entry = propertiesAfter === void 0 ? raw : raw.split(propertiesAfter)[0] ?? "";
+		const eq = entry.indexOf("=");
+		if (eq < 0) continue;
+		if (entry.slice(0, eq).trim() !== key) continue;
+		try {
+			return parseSpecId(decodeURIComponent(entry.slice(eq + 1).trim()));
+		} catch {
+			return;
+		}
+	}
+}
+/** Adds our key to an existing `baggage` header value, replacing any old one. */
+function writeBaggage(existing, specId) {
+	const kept = (existing ?? "").split(",").map((entry) => entry.trim()).filter((entry) => entry.length > 0 && !entry.startsWith(`ccqa.coverage=`));
+	kept.push(`${BAGGAGE_KEY}=${encodeURIComponent(specId)}`);
+	return kept.join(",");
+}
+//#endregion
+//#region src/coverage/middleware.ts
+/**
+* Entry points for servers `ccqa-tools/coverage/register` cannot wrap on its own:
+* anything that does not receive its requests from `node:http`.
+*
+* A framework running on plain Node needs none of this — the register hook
+* already opened the context before the framework saw the request.
+*/
+/** connect / express / fastify-compat middleware. */
+function coverageMiddleware() {
+	return function coverage(request, _response, next) {
+		const specId = specIdFromNodeHeaders(request.headers);
+		if (specId === void 0) {
+			next();
+			return;
+		}
+		runInSpec(specId, next);
+	};
+}
+/** Wraps a `Request` -> `Response` handler (Hono, Next.js route handlers, workerd). */
+function withCoverage(handler) {
+	return function covered(request, ...rest) {
+		const specId = readCookie(request.headers.get("cookie")) ?? readBaggage(request.headers.get("baggage"));
+		if (specId === void 0) return handler(request, ...rest);
+		return runInSpec(specId, () => handler(request, ...rest));
+	};
+}
+/**
+* Converts the cookie into a `baggage` header so downstream services — which
+* never see the browser's cookie jar — inherit the attribution. Call it where
+* the first service fans out, or in an edge middleware that forwards to one.
+*/
+function forwardHeaders(incoming, outgoing) {
+	const headers = outgoing ?? new Headers();
+	const specId = currentSpecId() ?? readCookie(incoming.get("cookie")) ?? readBaggage(incoming.get("baggage"));
+	if (specId !== void 0) headers.set("baggage", writeBaggage(headers.get("baggage") ?? incoming.get("baggage"), specId));
+	return headers;
+}
+function specIdFromNodeHeaders(headers) {
+	return readCookie(single(headers.cookie)) ?? readBaggage(single(headers.baggage));
+}
+function single(value) {
+	return Array.isArray(value) ? value[0] : value;
+}
+//#endregion
+exports.coverageMiddleware = coverageMiddleware;
+exports.forwardHeaders = forwardHeaders;
+exports.withCoverage = withCoverage;

package/dist/coverage/middleware.d.cts

@@ -0,0 +1,23 @@
+//#region src/coverage/middleware.d.ts
+/**
+ * Entry points for servers `ccqa-tools/coverage/register` cannot wrap on its own:
+ * anything that does not receive its requests from `node:http`.
+ *
+ * A framework running on plain Node needs none of this — the register hook
+ * already opened the context before the framework saw the request.
+ */
+interface NodeLikeRequest {
+  headers: Record<string, string | string[] | undefined>;
+}
+/** connect / express / fastify-compat middleware. */
+declare function coverageMiddleware(): (request: NodeLikeRequest, _response: unknown, next: () => void) => void;
+/** Wraps a `Request` -> `Response` handler (Hono, Next.js route handlers, workerd). */
+declare function withCoverage<A extends unknown[], R>(handler: (request: Request, ...rest: A) => R): (request: Request, ...rest: A) => R;
+/**
+ * Converts the cookie into a `baggage` header so downstream services — which
+ * never see the browser's cookie jar — inherit the attribution. Call it where
+ * the first service fans out, or in an edge middleware that forwards to one.
+ */
+declare function forwardHeaders(incoming: Headers, outgoing?: Headers): Headers;
+//#endregion
+export { coverageMiddleware, forwardHeaders, withCoverage };

package/dist/coverage/middleware.d.ts

@@ -0,0 +1,23 @@
+//#region src/coverage/middleware.d.ts
+/**
+ * Entry points for servers `ccqa-tools/coverage/register` cannot wrap on its own:
+ * anything that does not receive its requests from `node:http`.
+ *
+ * A framework running on plain Node needs none of this — the register hook
+ * already opened the context before the framework saw the request.
+ */
+interface NodeLikeRequest {
+  headers: Record<string, string | string[] | undefined>;
+}
+/** connect / express / fastify-compat middleware. */
+declare function coverageMiddleware(): (request: NodeLikeRequest, _response: unknown, next: () => void) => void;
+/** Wraps a `Request` -> `Response` handler (Hono, Next.js route handlers, workerd). */
+declare function withCoverage<A extends unknown[], R>(handler: (request: Request, ...rest: A) => R): (request: Request, ...rest: A) => R;
+/**
+ * Converts the cookie into a `baggage` header so downstream services — which
+ * never see the browser's cookie jar — inherit the attribution. Call it where
+ * the first service fans out, or in an edge middleware that forwards to one.
+ */
+declare function forwardHeaders(incoming: Headers, outgoing?: Headers): Headers;
+//#endregion
+export { coverageMiddleware, forwardHeaders, withCoverage };