@adhd/apigen-plugin-tracing 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# @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
+
+- Initial release. A `Layer` capability that emits one OTel span per dispatched operation
+  (operation id, transport, outcome, duration) to the `@adhd/sox-telemetry` JSONL sink, correlated
+  by `trace_id`. Declares an empty `target` capability for interface parity (`--type tracing` is a
+  valid no-op).
+
+### Patch Changes
+
+- The span's `apigen.transport` is now supplied by the engine from the operation plan's own
+  transport rather than inferred, so every transport — `http`, `grpc`, `mcp`, `cli` — reports
+  its own transport, never `undefined`. Reserved span keys (`apigen.op`, `apigen.transport`,
+  `trace_id`) can no longer be shadowed by an `envelopeAttrs` key of the same name; the reserved keys
+  always win. Streaming operations are quarantined to a unary span (see README): per-chunk records
+  with a chunk count are no longer emitted under the current `Next` contract.

package/README.md

@@ -1,3 +1,116 @@
-# Temporary Holding Version
+# @adhd/apigen-plugin-tracing
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> Layer plugin: one OTel span per dispatched operation, written as durable JSONL trace records.
+
+## What it does
+
+`@adhd/apigen-plugin-tracing` instruments **every operation dispatched through an apigen transport**
+— `http`, `grpc`, `mcp`, and `cli` — because all transports converge on a single composed invoker.
+For each dispatched operation it emits a span carrying the operation id, the transport, the outcome,
+and the duration, correlated by a `trace_id` that ties every span of one logical request together.
+
+Records are written through [`@adhd/sox-telemetry`](https://www.npmjs.com/package/@adhd/sox-telemetry)
+to the process's durable JSONL sink (`<dir>/<service>.<role>-<date>.jsonl`), so a second process — or
+the backlog graph — can reconstruct one request across transports.
+
+It is implemented as a **`Layer` capability** (one layer instruments all three transports). A
+`target` capability is declared for interface parity but emits nothing: `--type tracing` resolves to a
+valid no-op rather than an error. This mirrors `apigen-plugin-logger`.
+
+Tracing composes cleanly alongside the logger plugin — same seam, no coupling:
+
+```ts
+usePlugins: [tracingPlugin, loggerPlugin, batchPlugin];
+```
+
+## Install
+
+```bash
+pnpm add @adhd/apigen-plugin-tracing
+```
+
+## Usage
+
+### CLI — bare slug
+
+```bash
+apigen run --source ./api.ts --type mcp --use tracing
+```
+
+Also usable through the v2 multi-use option:
+
+```bash
+apigen run --source ./api.ts --type mcp --use @adhd/apigen-plugin-tracing
+# `--type tracing` is a valid no-op target (emits no files, throws no error)
+apigen run --source ./api.ts --type tracing
+```
+
+### Programmatic
+
+```ts
+import { tracingPlugin, makeTracingPlugin, TraceHandle } from '@adhd/apigen-plugin-tracing';
+
+// 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 — `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({
+  usePlugins: [
+    makeTracingPlugin({
+      serviceName: 'checkout',
+      envelopeAttrs: ['x-request-id'],
+    }),
+  ],
+});
+```
+
+### Annotating the live span from domain code
+
+The layer seeds a `TraceHandle` into `call.ctx`; read it back and add attributes to the live span:
+
+```ts
+import { TraceHandle } from '@adhd/apigen-plugin-tracing';
+
+export async function placeOrder(call, ...args) {
+  const trace = call.ctx.get(TraceHandle);
+  trace?.annotate({ 'order.region': region });
+  // …
+}
+```
+
+`annotate` is a no-op when the operation is not currently inside a unary span (e.g. before the
+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 | `<serviceName>.op`, `<serviceName>.transport`, `trace_id` |
+| `<serviceName>.<op>.finish` | info | the above + `duration_ms` |
+| `<serviceName>.<op>.error` | error | the above + `error` (the thrown message) |
+| `<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
+unresolved one, so the layer spans a streaming op only up to the point the stream is obtained — as a
+unary span. Per-chunk `.{start,finish,error}` records with a chunk count are **not** emitted. The
+`traceStream` helper remains in the package (directly unit-tested) behind a quarantine banner for a
+future reopen-span follow-up; `traceUnary` is the only layer path.
+
+## Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `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
+
+See [`@adhd/apigen-cli`](https://www.npmjs.com/package/@adhd/apigen-cli) for the full
+TypeScript-to-API system and the list of available plugins.

package/index.d.ts

@@ -0,0 +1,3 @@
+export type { TracingOptions } from './lib/plugin';
+export { TraceHandle, tracingPlugin, makeTracingPlugin } from './lib/plugin';
+export { default } from './lib/plugin';

package/index.js

@@ -0,0 +1 @@
+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

@@ -0,0 +1,151 @@
+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
+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 = v.get(this);
+		t !== void 0 && t.setAttributes(y(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 b(e, t) {
+	let n = {};
+	for (let r of t) {
+		let t = e[r];
+		t !== void 0 && (n[r] = t);
+	}
+	return n;
+}
+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 S(e, t, n, r, i) {
+	return u(t, y(n), async (a) => {
+		v.set(r, a);
+		try {
+			return await e;
+		} catch (e) {
+			throw c.error(`${i}.op.error`, {
+				...n,
+				span: t,
+				duration_ms: Date.now() - r.startedAt,
+				err: x(e)
+			}), e;
+		} finally {
+			v.delete(r);
+		}
+	});
+}
+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 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 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",
+	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: C({ serviceName: "apigen" }) }
+	}
+};
+function T(e) {
+	return {
+		...w,
+		capabilities: {
+			...w.capabilities,
+			layer: { layer: C(e) }
+		}
+	};
+}
+//#endregion
+export { _ as TraceHandle, w as default, w as tracingPlugin, T as makeTracingPlugin };

package/lib/plugin.d.ts

@@ -0,0 +1,109 @@
+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 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 `${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)`.
+ */
+export declare class TraceHandle {
+    /** Correlation id shared by every span of one logical request. */
+    readonly traceId: string;
+    /** Span name — `${serviceName}.${operation.id}`. */
+    readonly spanName: string;
+    /** Epoch millis at which the span opened. */
+    readonly startedAt: number;
+    constructor(
+    /** Correlation id shared by every span of one logical request. */
+    traceId: string, 
+    /** Span name — `${serviceName}.${operation.id}`. */
+    spanName: string, 
+    /** Epoch millis at which the span opened. */
+    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 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;
+}
+/**
+ * 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). 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 (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
+ * synchronously on entry and an async-generator wrapper yields each chunk unchanged, then
+ * emits `.finish` with the chunk count (or `.error` and re-throws).
+ */
+export declare function traceStream(downstream: AsyncIterable<Chunk>, spanName: string, attrs: Record<string, unknown>): AsyncIterable<Chunk>;
+/**
+ * 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>;
+/**
+ * Tracing plugin.
+ *
+ * Implemented as a **Layer** capability — a single layer instruments every transport (http, grpc,
+ * mcp, cli) because they all dispatch through one composed invoker. The `target` capability is
+ * declared but emits nothing (`generate()` returns `[]`), so `--type tracing` resolves to a valid
+ * no-op rather than an error — the same precedent as `apigen-plugin-logger`.
+ */
+export declare const tracingPlugin: Plugin<TracingOptions>;
+/** Configured factory — rebuilds the layer with `opts` (logger precedent). */
+export declare function makeTracingPlugin(opts: TracingOptions): Plugin<TracingOptions>;
+export default tracingPlugin;

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@adhd/apigen-plugin-tracing",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "dependencies": {
+    "@adhd/apigen-core-client": "^0.3.3",
+    "@adhd/sox-telemetry": "^0.4.1"
+  },
+  "main": "./index.js",
+  "module": "./index.mjs",
+  "types": "./index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Tracing plugin for apigen servers",
+  "keywords": [
+    "tracing",
+    "telemetry",
+    "otel",
+    "apigen",
+    "plugin",
+    "typescript"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PseudoSky/adhd.git",
+    "directory": "packages/apigen/apigen-plugin-tracing"
+  },
+  "homepage": "https://github.com/PseudoSky/adhd/tree/main/packages/apigen/apigen-plugin-tracing#readme",
+  "bugs": {
+    "url": "https://github.com/PseudoSky/adhd/issues"
+  }
+}