@adhd/apigen-plugin-tracing 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @adhd/apigen-plugin-tracing
 
+## 0.2.0 (2026-10-01)
+
+### ⚠️  Breaking Changes
+
+- **apigen-plugin-tracing:** `makeTracingPlugin(opts)` / `makeTraceLayer(opts)` now REQUIRE
+  `opts.serviceName` (previously the options object defaulted to `{}` with an implicit `'apigen'`
+  namespace). Reserved span attribute and event keys changed from `apigen.op` / `apigen.transport` /
+  `apigen.op.error` to `<serviceName>.op` / `<serviceName>.transport` / `<serviceName>.op.error`.
+  Every consumer must now pass an explicit `serviceName` (adhd products pass `'adhd'`) and read the
+  namespaced keys. 0.x breaking ⇒ minor.
+
+### ❤️  Thank You
+
+- pseudosky
+
 ## 0.1.0
 
 ### Minor Changes

package/README.md

@@ -50,11 +50,13 @@ apigen run --source ./api.ts --type tracing
 ```ts
 import { tracingPlugin, makeTracingPlugin, TraceHandle } from '@adhd/apigen-plugin-tracing';
 
-// default plugin — span prefix `apigen` (zero-config)
+// apigen's own singleton — span prefix `apigen` (for apigen's CLI and self-test only).
+// adhd products must NOT use this: they pass their own namespace explicitly (see below).
 run({ usePlugins: [tracingPlugin] });
 
-// `makeTracingPlugin(...)` is the configured entry point — use it to set the span prefix and
-// copy declared envelope headers onto every span.
+// `makeTracingPlugin(...)` is the configured entry point — `serviceName` is REQUIRED (no
+// implicit default) and is the namespace every emitted span/record/attribute is prefixed
+// with. Pass your product's namespace (e.g. `adhd`), plus any envelope headers to copy.
 
 // configured
 run({
@@ -82,16 +84,17 @@ export async function placeOrder(call, ...args) {
 ```
 
 `annotate` is a no-op when the operation is not currently inside a unary span (e.g. before the
-downstream resolved, or for a streaming call, which is logged rather than spanned).
+downstream resolved, or after the span has closed). A streaming call is still spanned — as a
+unary span covering only the point the stream is obtained (see [Records](#records)).
 
 ## Records
 
 | Event | Level | Carries |
 |---|---|---|
-| `<serviceName>.<op>.start` | info | `apigen.op`, `apigen.transport`, `trace_id` |
+| `<serviceName>.<op>.start` | info | `<serviceName>.op`, `<serviceName>.transport`, `trace_id` |
 | `<serviceName>.<op>.finish` | info | the above + `duration_ms` |
 | `<serviceName>.<op>.error` | error | the above + `error` (the thrown message) |
-| `apigen.op.error` | error | `apigen.op`, `apigen.transport`, `trace_id`, `span`, `duration_ms`, `err` |
+| `<serviceName>.op.error` | error | `<serviceName>.op`, `<serviceName>.transport`, `trace_id`, `span`, `duration_ms`, `err` |
 
 Streaming operations are **quarantined**: under the current `Next` contract
 (`() => Promise<LayerResult>`), an `AsyncIterable` can only be a *resolved* value, never an
@@ -104,7 +107,7 @@ future reopen-span follow-up; `traceUnary` is the only layer path.
 
 | Option | Type | Default | Description |
 |---|---|---|---|
-| `serviceName` | `string` | `'apigen'` | Span / record name prefix. |
+| `serviceName` | `string` | _(required)_ | Span / record / attribute name prefix — the emitting product's namespace (e.g. `adhd`). |
 | `envelopeAttrs` | `string[]` | `[]` | Extra `call.envelope` keys copied verbatim onto each span. |
 
 ## Part of the apigen toolchain

package/index.js

@@ -1 +1 @@
-Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:`Module`}});let e=require("@adhd/sox-telemetry");var t=class{constructor(e,t,n){this.traceId=e,this.spanName=t,this.startedAt=n}annotate(e){let t=n.get(this);t!==void 0&&t.setAttributes(r(e))}},n=new WeakMap;function r(e){let t={};for(let[n,r]of Object.entries(e))(typeof r==`string`||typeof r==`number`||typeof r==`boolean`)&&(t[n]=r);return t}function i(e,t){let n={};for(let r of t){let t=e[r];t!==void 0&&(n[r]=t)}return n}function a(e){return e instanceof Error?e.message:typeof e==`string`?e:typeof e==`object`&&e&&`message`in e&&typeof e.message==`string`?e.message:String(e)}function o(t,i,o,s){return(0,e.withSpan)(i,r(o),async r=>{n.set(s,r);try{return await t}catch(t){throw e.log.error(`apigen.op.error`,{...o,span:i,duration_ms:Date.now()-s.startedAt,err:a(t)}),t}finally{n.delete(s)}})}function s(n={}){let r=n.serviceName??`apigen`,a=n.envelopeAttrs??[];return(n,s)=>{let c=`${r}.${n.operation.id}`,l=(0,e.currentTraceId)()??(0,e.newTraceId)(),u=new t(l,c,Date.now());n.ctx.set(t,u);let d={...i(n.envelope,a),"apigen.op":n.operation.id,"apigen.transport":n.transport,trace_id:l};return(0,e.withTrace)(l,()=>o(Promise.resolve(s()),c,d,u))}}var c={id:`tracing`,description:`Layer plugin: emits one OTel span per dispatched operation (op id, transport, outcome, duration) to the sox-telemetry JSONL sink, correlated by trace_id.`,language:`ts`,optionsSchema:{type:`object`,properties:{serviceName:{type:`string`,description:`Span / record name prefix. Default: apigen.`},envelopeAttrs:{type:`array`,items:{type:`string`},description:`Extra envelope keys copied verbatim onto each span. Default: [].`}},additionalProperties:!1},capabilities:{target:{name:`tracing`,generate(){return[]}},layer:{layer:s()}}};function l(e={}){return{...c,capabilities:{...c.capabilities,layer:{layer:s(e)}}}}exports.TraceHandle=t,exports.default=c,exports.tracingPlugin=c,exports.makeTracingPlugin=l;
+Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:`Module`}});let e=require("node:crypto"),t=require("node:fs"),n=require("node:child_process"),r=require("node:path"),i=require("@adhd/sox-telemetry");function a(e){try{let t=(0,n.spawnSync)(`git`,[`rev-parse`,...e],{cwd:process.cwd(),encoding:`utf8`,timeout:2e3});if(t.status===0&&t.stdout){let e=t.stdout.trim();return e.length>0?e:null}}catch{}return null}function o(){let n=process.argv[1];if(n===void 0)return null;try{return`sha256:${(0,e.createHash)(`sha256`).update((0,t.readFileSync)(n)).digest(`hex`)}`}catch{return null}}function s(){let e=a([`--show-toplevel`]),t=a([`--path-format=absolute`,`--git-common-dir`]);return e===null||t===null?`none`:/[\\/]\.git$/.test(t)&&(0,r.resolve)((0,r.dirname)(t))!==(0,r.resolve)(e)?`linked`:`main`}var c=null;function l(){if(c===null){let t=process.env.ADHD_SESSION_ID,n=process.env.npm_package_version;c={sessionId:t!==void 0&&t.length>0?t:(0,e.randomUUID)(),worktree:s(),release:{version:n!==void 0&&n.length>0?n:null,gitSha:a([`HEAD`]),artifactSha256:o()}}}return c}var u=class{constructor(e,t,n){this.traceId=e,this.spanName=t,this.startedAt=n}annotate(e){let t=d.get(this);t!==void 0&&t.setAttributes(f(e))}},d=new WeakMap;function f(e){let t={};for(let[n,r]of Object.entries(e))(typeof r==`string`||typeof r==`number`||typeof r==`boolean`)&&(t[n]=r);return t}function p(e,t){let n={};for(let r of t){let t=e[r];t!==void 0&&(n[r]=t)}return n}function m(e){return e instanceof Error?e.message:typeof e==`string`?e:typeof e==`object`&&e&&`message`in e&&typeof e.message==`string`?e.message:String(e)}function h(e,t,n,r,a){return(0,i.withSpan)(t,f(n),async o=>{d.set(r,o);try{return await e}catch(e){throw i.log.error(`${a}.op.error`,{...n,span:t,duration_ms:Date.now()-r.startedAt,err:m(e)}),e}finally{d.delete(r)}})}function g(e){let t=e.serviceName;if(typeof t!=`string`||t.trim()===``)throw Error('@adhd/apigen-plugin-tracing: `serviceName` is required and must be a non-empty string — it namespaces every span name, attribute key, and error record. Construct the plugin explicitly, e.g. `makeTracingPlugin({ serviceName: "adhd" })`.');let n=e.envelopeAttrs??[];return(e,r)=>{let a=`${t}.${e.operation.id}`,o=(0,i.currentTraceId)()??(0,i.newTraceId)(),s=new u(o,a,Date.now());e.ctx.set(u,s);let c=l(),d={...p(e.envelope,n),[`${t}.op`]:e.operation.id,[`${t}.transport`]:e.transport,trace_id:o,session_id:c.sessionId,worktree:c.worktree,role:(0,i.currentRuntimeState)().role};return c.release.version!==null&&(d[`release.version`]=c.release.version),c.release.gitSha!==null&&(d[`release.git_sha`]=c.release.gitSha),c.release.artifactSha256!==null&&(d[`release.artifact_sha256`]=c.release.artifactSha256),(0,i.withTrace)(o,()=>h(Promise.resolve(r()),a,d,s,t))}}var _={id:`tracing`,description:`Layer plugin: emits one OTel span per dispatched operation (op id, transport, outcome, duration) to the sox-telemetry JSONL sink, correlated by trace_id.`,language:`ts`,optionsSchema:{type:`object`,properties:{serviceName:{type:`string`,description:`Span / record / attribute name prefix. REQUIRED — the emitting product namespace (e.g. adhd).`},envelopeAttrs:{type:`array`,items:{type:`string`},description:`Extra envelope keys copied verbatim onto each span. Default: [].`}},required:[`serviceName`],additionalProperties:!1},capabilities:{target:{name:`tracing`,generate(){return[]}},layer:{layer:g({serviceName:`apigen`})}}};function v(e){return{..._,capabilities:{..._.capabilities,layer:{layer:g(e)}}}}exports.TraceHandle=u,exports.default=_,exports.tracingPlugin=_,exports.makeTracingPlugin=v;

package/index.mjs

@@ -1,20 +1,67 @@
-import { currentTraceId as e, log as t, newTraceId as n, withSpan as r, withTrace as i } from "@adhd/sox-telemetry";
+import { createHash as e, randomUUID as t } from "node:crypto";
+import { readFileSync as n } from "node:fs";
+import { spawnSync as r } from "node:child_process";
+import { dirname as i, resolve as a } from "node:path";
+import { currentRuntimeState as o, currentTraceId as s, log as c, newTraceId as l, withSpan as u, withTrace as d } from "@adhd/sox-telemetry";
 //#region src/lib/plugin.ts
-var a = class {
+function f(e) {
+	try {
+		let t = r("git", ["rev-parse", ...e], {
+			cwd: process.cwd(),
+			encoding: "utf8",
+			timeout: 2e3
+		});
+		if (t.status === 0 && t.stdout) {
+			let e = t.stdout.trim();
+			return e.length > 0 ? e : null;
+		}
+	} catch {}
+	return null;
+}
+function p() {
+	let t = process.argv[1];
+	if (t === void 0) return null;
+	try {
+		return `sha256:${e("sha256").update(n(t)).digest("hex")}`;
+	} catch {
+		return null;
+	}
+}
+function m() {
+	let e = f(["--show-toplevel"]), t = f(["--path-format=absolute", "--git-common-dir"]);
+	return e === null || t === null ? "none" : /[\\/]\.git$/.test(t) && a(i(t)) !== a(e) ? "linked" : "main";
+}
+var h = null;
+function g() {
+	if (h === null) {
+		let e = process.env.ADHD_SESSION_ID, n = process.env.npm_package_version;
+		h = {
+			sessionId: e !== void 0 && e.length > 0 ? e : t(),
+			worktree: m(),
+			release: {
+				version: n !== void 0 && n.length > 0 ? n : null,
+				gitSha: f(["HEAD"]),
+				artifactSha256: p()
+			}
+		};
+	}
+	return h;
+}
+var _ = class {
 	constructor(e, t, n) {
 		this.traceId = e, this.spanName = t, this.startedAt = n;
 	}
 	annotate(e) {
-		let t = o.get(this);
-		t !== void 0 && t.setAttributes(s(e));
+		let t = v.get(this);
+		t !== void 0 && t.setAttributes(y(e));
 	}
-}, o = /* @__PURE__ */ new WeakMap();
-function s(e) {
+}, v = /* @__PURE__ */ new WeakMap();
+function y(e) {
 	let t = {};
 	for (let [n, r] of Object.entries(e)) (typeof r == "string" || typeof r == "number" || typeof r == "boolean") && (t[n] = r);
 	return t;
 }
-function c(e, t) {
+function b(e, t) {
 	let n = {};
 	for (let r of t) {
 		let t = e[r];
@@ -22,41 +69,46 @@ function c(e, t) {
 	}
 	return n;
 }
-function l(e) {
+function x(e) {
 	return e instanceof Error ? e.message : typeof e == "string" ? e : typeof e == "object" && e && "message" in e && typeof e.message == "string" ? e.message : String(e);
 }
-function u(e, n, i, a) {
-	return r(n, s(i), async (r) => {
-		o.set(a, r);
+function S(e, t, n, r, i) {
+	return u(t, y(n), async (a) => {
+		v.set(r, a);
 		try {
 			return await e;
 		} catch (e) {
-			throw t.error("apigen.op.error", {
-				...i,
-				span: n,
-				duration_ms: Date.now() - a.startedAt,
-				err: l(e)
+			throw c.error(`${i}.op.error`, {
+				...n,
+				span: t,
+				duration_ms: Date.now() - r.startedAt,
+				err: x(e)
 			}), e;
 		} finally {
-			o.delete(a);
+			v.delete(r);
 		}
 	});
 }
-function d(t = {}) {
-	let r = t.serviceName ?? "apigen", o = t.envelopeAttrs ?? [];
-	return (t, s) => {
-		let l = `${r}.${t.operation.id}`, d = e() ?? n(), f = new a(d, l, Date.now());
-		t.ctx.set(a, f);
-		let p = {
-			...c(t.envelope, o),
-			"apigen.op": t.operation.id,
-			"apigen.transport": t.transport,
-			trace_id: d
+function C(e) {
+	let t = e.serviceName;
+	if (typeof t != "string" || t.trim() === "") throw Error("@adhd/apigen-plugin-tracing: `serviceName` is required and must be a non-empty string — it namespaces every span name, attribute key, and error record. Construct the plugin explicitly, e.g. `makeTracingPlugin({ serviceName: \"adhd\" })`.");
+	let n = e.envelopeAttrs ?? [];
+	return (e, r) => {
+		let i = `${t}.${e.operation.id}`, a = s() ?? l(), c = new _(a, i, Date.now());
+		e.ctx.set(_, c);
+		let u = g(), f = {
+			...b(e.envelope, n),
+			[`${t}.op`]: e.operation.id,
+			[`${t}.transport`]: e.transport,
+			trace_id: a,
+			session_id: u.sessionId,
+			worktree: u.worktree,
+			role: o().role
 		};
-		return i(d, () => u(Promise.resolve(s()), l, p, f));
+		return u.release.version !== null && (f["release.version"] = u.release.version), u.release.gitSha !== null && (f["release.git_sha"] = u.release.gitSha), u.release.artifactSha256 !== null && (f["release.artifact_sha256"] = u.release.artifactSha256), d(a, () => S(Promise.resolve(r()), i, f, c, t));
 	};
 }
-var f = {
+var w = {
 	id: "tracing",
 	description: "Layer plugin: emits one OTel span per dispatched operation (op id, transport, outcome, duration) to the sox-telemetry JSONL sink, correlated by trace_id.",
 	language: "ts",
@@ -65,7 +117,7 @@ var f = {
 		properties: {
 			serviceName: {
 				type: "string",
-				description: "Span / record name prefix. Default: apigen."
+				description: "Span / record / attribute name prefix. REQUIRED — the emitting product namespace (e.g. adhd)."
 			},
 			envelopeAttrs: {
 				type: "array",
@@ -73,6 +125,7 @@ var f = {
 				description: "Extra envelope keys copied verbatim onto each span. Default: []."
 			}
 		},
+		required: ["serviceName"],
 		additionalProperties: !1
 	},
 	capabilities: {
@@ -82,17 +135,17 @@ var f = {
 				return [];
 			}
 		},
-		layer: { layer: d() }
+		layer: { layer: C({ serviceName: "apigen" }) }
 	}
 };
-function p(e = {}) {
+function T(e) {
 	return {
-		...f,
+		...w,
 		capabilities: {
-			...f.capabilities,
-			layer: { layer: d(e) }
+			...w.capabilities,
+			layer: { layer: C(e) }
 		}
 	};
 }
 //#endregion
-export { a as TraceHandle, f as default, f as tracingPlugin, p as makeTracingPlugin };
+export { _ as TraceHandle, w as default, w as tracingPlugin, T as makeTracingPlugin };

package/lib/plugin.d.ts

@@ -1,20 +1,46 @@
 import { Plugin, Call, Next, Result, Chunk } from '@adhd/apigen-core-client';
 
+/**
+ * Where `process.cwd()` sits relative to git — three-valued so the main checkout and a
+ * cwd outside any repository (a boolean reported both as the same value) stay
+ * distinguishable when records are aggregated.
+ */
+export type WorktreeKind = 'main' | 'linked' | 'none';
+/**
+ * Classify `process.cwd()` as a LINKED git worktree, a repository's main checkout, or
+ * nothing at all:
+ *
+ *   - `'linked'` — inside a LINKED worktree: `--git-common-dir` names the main
+ *                  checkout's `.git` directory (a path ending in `.git`), and its
+ *                  parent is not this worktree's own `--show-toplevel`.
+ *   - `'main'`   — inside a repository but not a linked worktree (the main checkout).
+ *   - `'none'`   — not inside any repository (either `git rev-parse` probe fails).
+ *
+ * Exported only so all three values can be unit-tested directly — the same
+ * test-only, not-in-the-public-API precedent as `traceStream`; NOT re-exported
+ * from `src/index.ts`.
+ */
+export declare function classifyWorktree(): WorktreeKind;
 /**
  * Options for {@link makeTracingPlugin}.
  *
  * Layer plugins receive no opts at call time — `LayerCapability.layer` is invoked with only
  * `(call, next)` — so configuration is a factory, exactly as `makeLoggerPlugin` does it.
  */
-export interface TracingOptions {
-    /** Span / record name prefix. Default: `'apigen'`. */
-    serviceName?: string;
+export type TracingOptions = {
+    /**
+     * Span / record / attribute name prefix — the emitting product's namespace. REQUIRED: there
+     * is no implicit default, so a product cannot silently emit another product's telemetry.
+     * adhd products pass `'adhd'`; apigen's own CLI and self-test pass `'apigen'` explicitly.
+     */
+    serviceName: string;
     /**
      * Extra attribute keys copied verbatim from `call.envelope` onto each span. Default: `[]`
-     * (only the built-in attrs `apigen.op`, `apigen.transport`, `trace_id` are emitted).
+     * (only the built-in attrs `${serviceName}.op`, `${serviceName}.transport`, `trace_id` are
+     * emitted).
      */
     envelopeAttrs?: readonly string[];
-}
+};
 /**
  * Per-call trace handle, seeded into `call.ctx`. The class is the ctx token: domain code reads
  * it back with `call.ctx.get(TraceHandle)`.
@@ -35,8 +61,9 @@ export declare class TraceHandle {
     startedAt: number);
     /**
      * Add attributes to the live span from domain code — opt-in. A no-op when the operation is
-     * not currently inside a unary span (e.g. before the downstream resolved, or for a streaming
-     * call, which is logged rather than spanned).
+     * not currently inside a unary span (e.g. before the downstream resolved, or after the span
+     * has closed). Streaming is not special-cased: the layer spans a streaming op as a unary
+     * span covering only the point the stream is obtained.
      */
     annotate(fields: Record<string, unknown>): void;
 }
@@ -44,16 +71,18 @@ export declare class TraceHandle {
  * QUARANTINED — unreachable under the current `Next` contract; see CONTRACT-FIX §4.
  * Exported only so the streaming branch can be exercised by a direct unit test; no layer
  * path reaches it (a `Next` resolves to a `LayerResult`, so this detector can never be
- * true for the unresolved `next()` promise). Retained — never deleted — pending a `Next`
- * that can yield an iterable before resolution.
+ * true for the unresolved `next()` promise). Not re-exported from the package entry
+ * (`src/index.ts`), so it is not part of the public API either. Retained — never
+ * deleted — pending a `Next` that can yield an iterable before resolution.
  */
 export declare function isAsyncIterable(value: unknown): value is AsyncIterable<Chunk>;
 /**
  * QUARANTINED — unreachable under the current `Next` contract; see CONTRACT-FIX §4.
  * The layer no longer branches on `next()` (an `AsyncIterable` can only be a *resolved*
  * value, never the unresolved promise), so this is retained with its body intact and
- * exported solely for a direct unit test. Do NOT re-wire it into the layer by awaiting
- * `next()` first — that would destroy the span-before-body invariant guarded by
+ * exported solely for a direct unit test (and not re-exported from the package entry
+ * `src/index.ts`, so not part of the public API). Do NOT re-wire it into the layer by
+ * awaiting `next()` first — that would destroy the span-before-body invariant guarded by
  * `plugin.spec.ts` (the hang-visibility test).
  *
  * Streaming branch — `withSpan` cannot await an iterable, so the `.start` record is emitted
@@ -65,7 +94,7 @@ export declare function traceStream(downstream: AsyncIterable<Chunk>, spanName:
  * Build the tracing layer for a given configuration. The returned layer calls `next()` exactly
  * once and returns its resolved value (or iterable) unchanged, wrapping it in a span.
  */
-export declare function makeTraceLayer(opts?: TracingOptions): (call: Call, next: Next) => Promise<Result> | AsyncIterable<Chunk>;
+export declare function makeTraceLayer(opts: TracingOptions): (call: Call, next: Next) => Promise<Result> | AsyncIterable<Chunk>;
 /**
  * Tracing plugin.
  *
@@ -76,5 +105,5 @@ export declare function makeTraceLayer(opts?: TracingOptions): (call: Call, next
  */
 export declare const tracingPlugin: Plugin<TracingOptions>;
 /** Configured factory — rebuilds the layer with `opts` (logger precedent). */
-export declare function makeTracingPlugin(opts?: TracingOptions): Plugin<TracingOptions>;
+export declare function makeTracingPlugin(opts: TracingOptions): Plugin<TracingOptions>;
 export default tracingPlugin;

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@adhd/apigen-plugin-tracing",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "dependencies": {
     "@adhd/apigen-core-client": "^0.3.3",
-    "@adhd/sox-telemetry": "^0.3.2"
+    "@adhd/sox-telemetry": "^0.4.1"
   },
   "main": "./index.js",
   "module": "./index.mjs",