@graphorin/observability 0.5.0

package/dist/replay/replay.js

@@ -0,0 +1,173 @@
+import { compareSensitivityTiers, createRedactionValidator } from "../redaction/validator.js";
+import { sanitizeRecord } from "../exporters/with-validation.js";
+
+//#region src/replay/replay.ts
+const DEFAULT_VALIDATOR = createRedactionValidator({ minTier: "public" });
+const DEFAULT_ACTOR = {
+	kind: "system",
+	id: "in-process"
+};
+/**
+* Build a replay primitive. The returned object exposes a single
+* `run(...)` async iterator that yields {@link ReplayEvent} records.
+*
+* Sanitized mode is the default and applies the configured
+* {@link RedactionValidatorInstance} to every record. Raw mode
+* requires the `canReadRaw` callback to return `true` AND emits an
+* audit log entry on every invocation.
+*
+* @stable
+*/
+function createReplay(opts = {}) {
+	const validator = opts.validator ?? DEFAULT_VALIDATOR;
+	const audit = opts.audit;
+	const defaultActor = opts.defaultActor ?? DEFAULT_ACTOR;
+	const canReadRaw = opts.canReadRaw ?? (() => true);
+	return { async *run(input) {
+		const mode = input.mode ?? "sanitized";
+		const minSensitivity = input.minSensitivity ?? "public";
+		const actor = input.actor ?? defaultActor;
+		const start = Date.now();
+		if (mode === "raw" && !canReadRaw({ target: input.target })) {
+			emitAudit(audit, {
+				action: "trace.replay.accessed",
+				actor,
+				target: input.target,
+				decision: "denied",
+				metadata: {
+					mode,
+					minSensitivity,
+					eventCount: 0,
+					durationMs: Date.now() - start
+				}
+			});
+			yield {
+				type: "replay.start",
+				target: input.target,
+				mode
+			};
+			yield {
+				type: "replay.skipped",
+				reason: "access-denied",
+				spanId: input.target
+			};
+			yield {
+				type: "replay.end",
+				durationMs: Date.now() - start,
+				eventsEmitted: 0,
+				eventsSkipped: 1
+			};
+			return;
+		}
+		let emitted = 0;
+		let skipped = 0;
+		let started = false;
+		let reachedFrom = input.fromSpanId === void 0;
+		const iterator = isAsyncIterable(input.source) ? input.source[Symbol.asyncIterator]() : asAsync(input.source[Symbol.iterator]());
+		try {
+			while (true) {
+				const next = await iterator.next();
+				if (next.done === true) break;
+				const record = next.value;
+				if (!started) {
+					started = true;
+					yield {
+						type: "replay.start",
+						target: input.target,
+						mode
+					};
+				}
+				if (!reachedFrom) if (record.id === input.fromSpanId) reachedFrom = true;
+				else continue;
+				if (mode === "raw") {
+					yield {
+						type: "replay.event",
+						span: record,
+						sanitized: false
+					};
+					emitted += 1;
+					continue;
+				}
+				if (skipBySensitivity(record, minSensitivity)) {
+					skipped += 1;
+					yield {
+						type: "replay.skipped",
+						reason: "sensitivity",
+						spanId: record.id
+					};
+					continue;
+				}
+				const sanitized = sanitizeRecord(record, validator);
+				if (sanitized.droppedReason !== void 0) {
+					skipped += 1;
+					yield {
+						type: "replay.skipped",
+						reason: "redaction-violation",
+						spanId: record.id
+					};
+					continue;
+				}
+				yield {
+					type: "replay.event",
+					span: sanitized,
+					sanitized: true
+				};
+				emitted += 1;
+			}
+		} finally {
+			const durationMs = Date.now() - start;
+			if (!started) yield {
+				type: "replay.start",
+				target: input.target,
+				mode
+			};
+			emitAudit(audit, {
+				action: "trace.replay.accessed",
+				actor,
+				target: input.target,
+				decision: "success",
+				metadata: {
+					mode,
+					minSensitivity,
+					...input.fromSpanId === void 0 ? {} : { fromSpanId: input.fromSpanId },
+					eventCount: emitted,
+					durationMs
+				}
+			});
+			yield {
+				type: "replay.end",
+				durationMs,
+				eventsEmitted: emitted,
+				eventsSkipped: skipped
+			};
+		}
+	} };
+}
+function emitAudit(bridge, event) {
+	if (bridge === void 0) return;
+	try {
+		bridge.emit(event);
+	} catch {}
+}
+function skipBySensitivity(record, floor) {
+	if (record.sensitivityByAttribute === void 0) return false;
+	for (const value of Object.values(record.sensitivityByAttribute)) if (typeof value === "string") {
+		const tier = value;
+		if (tier === "public" || tier === "internal" || tier === "secret") {
+			if (compareSensitivityTiers(tier, floor) > 0) return true;
+		}
+	}
+	return false;
+}
+function isAsyncIterable(value) {
+	return value !== null && typeof value === "object" && Symbol.asyncIterator in value;
+}
+function asAsync(it) {
+	return { next() {
+		return Promise.resolve(it.next());
+	} };
+}
+
+//#endregion
+export { createReplay };
+//# sourceMappingURL=replay.js.map

package/dist/replay/replay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay.js","names":["DEFAULT_ACTOR: ReplayAuditEvent['actor']","validator: RedactionValidatorInstance","audit: ReplayAuditBridge | undefined","minSensitivity: Sensitivity"],"sources":["../../src/replay/replay.ts"],"sourcesContent":["/**\n * `createReplay(...)` — sanitized-by-default replay primitives.\n *\n * Replay never opens the underlying file directly; callers feed it an\n * iterable of `SpanRecord`s. The {@link createTraceLogReader} helper\n * (file-backed JSONL) and `getTraceLog(...)` aggregate utility live\n * alongside this module.\n *\n * @packageDocumentation\n */\n\nimport type { Sensitivity } from '@graphorin/core';\n\nimport type { SpanRecord } from '../exporters/types.js';\nimport { sanitizeRecord } from '../exporters/with-validation.js';\nimport type { RedactionValidatorInstance } from '../redaction/types.js';\nimport { compareSensitivityTiers, createRedactionValidator } from '../redaction/validator.js';\n\nimport type {\n  ReplayAuditBridge,\n  ReplayAuditEvent,\n  ReplayEvent,\n  ReplayOptions,\n  ReplayRunInput,\n} from './types.js';\n\nconst DEFAULT_VALIDATOR = createRedactionValidator({ minTier: 'public' });\nconst DEFAULT_ACTOR: ReplayAuditEvent['actor'] = { kind: 'system', id: 'in-process' };\n\n/**\n * @stable\n */\nexport interface Replay {\n  run(input: ReplayRunInput): AsyncIterable<ReplayEvent>;\n}\n\n/**\n * Build a replay primitive. The returned object exposes a single\n * `run(...)` async iterator that yields {@link ReplayEvent} records.\n *\n * Sanitized mode is the default and applies the configured\n * {@link RedactionValidatorInstance} to every record. Raw mode\n * requires the `canReadRaw` callback to return `true` AND emits an\n * audit log entry on every invocation.\n *\n * @stable\n */\nexport function createReplay(opts: ReplayOptions = {}): Replay {\n  const validator: RedactionValidatorInstance = opts.validator ?? DEFAULT_VALIDATOR;\n  const audit: ReplayAuditBridge | undefined = opts.audit;\n  const defaultActor = opts.defaultActor ?? DEFAULT_ACTOR;\n  const canReadRaw = opts.canReadRaw ?? (() => true);\n\n  return {\n    async *run(input: ReplayRunInput): AsyncIterable<ReplayEvent> {\n      const mode = input.mode ?? 'sanitized';\n      const minSensitivity: Sensitivity = input.minSensitivity ?? 'public';\n      const actor = input.actor ?? defaultActor;\n      const start = Date.now();\n\n      if (mode === 'raw' && !canReadRaw({ target: input.target })) {\n        emitAudit(audit, {\n          action: 'trace.replay.accessed',\n          actor,\n          target: input.target,\n          decision: 'denied',\n          metadata: { mode, minSensitivity, eventCount: 0, durationMs: Date.now() - start },\n        });\n        yield { type: 'replay.start', target: input.target, mode };\n        yield { type: 'replay.skipped', reason: 'access-denied', spanId: input.target };\n        yield {\n          type: 'replay.end',\n          durationMs: Date.now() - start,\n          eventsEmitted: 0,\n          eventsSkipped: 1,\n        };\n        return;\n      }\n\n      let emitted = 0;\n      let skipped = 0;\n      let started = false;\n      let reachedFrom = input.fromSpanId === undefined;\n\n      const iterator = isAsyncIterable(input.source)\n        ? input.source[Symbol.asyncIterator]()\n        : asAsync(input.source[Symbol.iterator]());\n\n      try {\n        while (true) {\n          const next = await iterator.next();\n          if (next.done === true) break;\n          const record = next.value;\n\n          if (!started) {\n            started = true;\n            yield { type: 'replay.start', target: input.target, mode };\n          }\n\n          if (!reachedFrom) {\n            if (record.id === input.fromSpanId) reachedFrom = true;\n            else continue;\n          }\n\n          if (mode === 'raw') {\n            yield { type: 'replay.event', span: record, sanitized: false };\n            emitted += 1;\n            continue;\n          }\n\n          if (skipBySensitivity(record, minSensitivity)) {\n            skipped += 1;\n            yield { type: 'replay.skipped', reason: 'sensitivity', spanId: record.id };\n            continue;\n          }\n\n          const sanitized = sanitizeRecord(record, validator);\n          // RP-18: sanitization is attribute-granular and never drops the whole\n          // span. A record arrives pre-flagged with `droppedReason` only if an\n          // upstream stage marked it; honour that, otherwise replay the\n          // stripped span.\n          if (sanitized.droppedReason !== undefined) {\n            skipped += 1;\n            yield {\n              type: 'replay.skipped',\n              reason: 'redaction-violation',\n              spanId: record.id,\n            };\n            continue;\n          }\n\n          yield { type: 'replay.event', span: sanitized, sanitized: true };\n          emitted += 1;\n        }\n      } finally {\n        const durationMs = Date.now() - start;\n        if (!started) {\n          yield { type: 'replay.start', target: input.target, mode };\n        }\n        emitAudit(audit, {\n          action: 'trace.replay.accessed',\n          actor,\n          target: input.target,\n          decision: 'success',\n          metadata: {\n            mode,\n            minSensitivity,\n            ...(input.fromSpanId === undefined ? {} : { fromSpanId: input.fromSpanId }),\n            eventCount: emitted,\n            durationMs,\n          },\n        });\n        yield {\n          type: 'replay.end',\n          durationMs,\n          eventsEmitted: emitted,\n          eventsSkipped: skipped,\n        };\n      }\n    },\n  };\n}\n\nfunction emitAudit(bridge: ReplayAuditBridge | undefined, event: ReplayAuditEvent): void {\n  if (bridge === undefined) return;\n  try {\n    bridge.emit(event);\n  } catch {\n    // Audit listener errors must never break the replay pipeline.\n  }\n}\n\nfunction skipBySensitivity(record: SpanRecord, floor: Sensitivity): boolean {\n  if (record.sensitivityByAttribute === undefined) return false;\n  for (const value of Object.values(record.sensitivityByAttribute)) {\n    if (typeof value === 'string') {\n      const tier = value as Sensitivity;\n      if (tier === 'public' || tier === 'internal' || tier === 'secret') {\n        if (compareSensitivityTiers(tier, floor) > 0) return true;\n      }\n    }\n  }\n  return false;\n}\n\nfunction isAsyncIterable<T>(value: unknown): value is AsyncIterable<T> {\n  return value !== null && typeof value === 'object' && Symbol.asyncIterator in (value as object);\n}\n\nfunction asAsync<T>(it: Iterator<T>): AsyncIterator<T> {\n  return {\n    next(): Promise<IteratorResult<T>> {\n      return Promise.resolve(it.next());\n    },\n  };\n}\n"],"mappings":"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"}

package/dist/replay/types.d.ts

@@ -0,0 +1,110 @@
+import { SpanRecord } from "../exporters/types.js";
+import { RedactionValidatorInstance } from "../redaction/types.js";
+import { Sensitivity } from "@graphorin/core";
+
+//#region src/replay/types.d.ts
+
+/**
+ * Replay scope hint. Server mode requires `'raw'` to be backed by a
+ * token carrying the `traces:read:raw` scope. The library mode uses
+ * the same flag but without scope enforcement (the server is the only
+ * boundary that can grant `'raw'`).
+ *
+ * @stable
+ */
+type ReplayMode = 'sanitized' | 'raw';
+/**
+ * Audit-bridge contract used by the replay layer. Every replay
+ * invocation emits one entry through the bridge — sanitized + raw
+ * alike. The actual audit storage lives in `@graphorin/security`; the
+ * replay layer keeps the bridge generic so the package stays free of
+ * a hard dependency on the security package.
+ *
+ * @stable
+ */
+interface ReplayAuditBridge {
+  emit(event: ReplayAuditEvent): void;
+}
+/**
+ * Sanitized event passed to the audit bridge.
+ *
+ * @stable
+ */
+interface ReplayAuditEvent {
+  readonly action: 'trace.replay.accessed';
+  readonly actor: {
+    readonly kind: 'token' | 'cli' | 'agent' | 'system';
+    readonly id: string;
+  };
+  readonly target: string;
+  readonly decision: 'success' | 'denied';
+  readonly metadata: {
+    readonly mode: ReplayMode;
+    readonly minSensitivity: Sensitivity;
+    readonly fromSpanId?: string;
+    readonly eventCount: number;
+    readonly durationMs: number;
+  };
+}
+/**
+ * Single record yielded by the replay iterator.
+ *
+ * @stable
+ */
+type ReplayEvent = {
+  readonly type: 'replay.start';
+  readonly target: string;
+  readonly mode: ReplayMode;
+  readonly eventCount?: number;
+} | {
+  readonly type: 'replay.event';
+  readonly span: SpanRecord;
+  readonly sanitized: boolean;
+} | {
+  readonly type: 'replay.skipped';
+  readonly reason: 'sensitivity' | 'redaction-violation' | 'access-denied';
+  readonly spanId: string;
+} | {
+  readonly type: 'replay.end';
+  readonly durationMs: number;
+  readonly eventsEmitted: number;
+  readonly eventsSkipped: number;
+};
+/**
+ * Configuration shape for {@link createReplay}.
+ *
+ * @stable
+ */
+interface ReplayOptions {
+  /** Validator used to sanitize records when `mode === 'sanitized'`. */
+  readonly validator?: RedactionValidatorInstance;
+  /** Optional audit bridge — called once per replay invocation. */
+  readonly audit?: ReplayAuditBridge;
+  /** Default actor reported via `audit.actor` when none is supplied. */
+  readonly defaultActor?: ReplayAuditEvent['actor'];
+  /**
+   * Scope check invoked when the caller asks for `mode: 'raw'`. Returns
+   * `true` to allow, `false` to deny. The server (Phase 14) wires this
+   * to the `traces:read:raw` token scope; in library mode it defaults
+   * to `() => true` (operators trust their own process).
+   */
+  readonly canReadRaw?: (context: {
+    readonly target: string;
+  }) => boolean;
+}
+/**
+ * Per-call options consumed by `Replay.run(...)`.
+ *
+ * @stable
+ */
+interface ReplayRunInput {
+  readonly source: AsyncIterable<SpanRecord> | Iterable<SpanRecord>;
+  readonly target: string;
+  readonly mode?: ReplayMode;
+  readonly minSensitivity?: Sensitivity;
+  readonly fromSpanId?: string;
+  readonly actor?: ReplayAuditEvent['actor'];
+}
+//#endregion
+export { ReplayAuditBridge, ReplayAuditEvent, ReplayEvent, ReplayMode, ReplayOptions, ReplayRunInput };
+//# sourceMappingURL=types.d.ts.map

package/dist/replay/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../src/replay/types.ts"],"sourcesContent":[],"mappings":";;;;;;AA0DA;AAyBA;;;;;AAqBA;;AACmB,KAtFP,UAAA,GAsFO,WAAA,GAAA,KAAA;;;;;;;;;;UA3EF,iBAAA;cACH;;;;;;;UAQG,gBAAA;;;;;;;;;mBAME;6BACU;;;;;;;;;;;KAYjB,WAAA;;;iBAIS;;;;iBAG+B;;;;;;;;;;;;;;;;;UAkBnC,aAAA;;uBAEM;;mBAEJ;;0BAEO;;;;;;;;;;;;;;;;UAeT,cAAA;mBACE,cAAc,cAAc,SAAS;;kBAEtC;4BACU;;mBAET"}

package/dist/telemetry/index.d.ts

@@ -0,0 +1,63 @@
+//#region src/telemetry/index.d.ts
+/**
+ * Zero-default telemetry stub.
+ *
+ * The framework promises to make zero outbound network calls without
+ * an explicit user action. This module exists so consumers can:
+ *
+ * - inspect the telemetry posture from CLI / health endpoints,
+ * - register the reserved `GRAPHORIN_TELEMETRY` / `GRAPHORIN_NO_PHONE_HOME`
+ *   environment variables for forward compatibility,
+ * - assert in tests that no implicit telemetry surface exists.
+ *
+ * Attempting to enable telemetry pre-v0.2 returns a sentinel result; it
+ * never opens a socket.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Result returned by {@link getTelemetryStatus}.
+ *
+ * @stable
+ */
+interface TelemetryStatus {
+  /** Always `false` in v0.1. Reserved field. */
+  readonly enabled: false;
+  /** Plain-English explanation of the current state. */
+  readonly reason: string;
+  /** Resolved value of `GRAPHORIN_TELEMETRY` (if any). */
+  readonly env?: string;
+  /** Resolved value of `GRAPHORIN_NO_PHONE_HOME` (if any). */
+  readonly noPhoneHome?: string;
+}
+/**
+ * Snapshot of the telemetry posture. Reads from `process.env` once
+ * unless `env` is provided.
+ *
+ * @stable
+ */
+declare function getTelemetryStatus(env?: NodeJS.ProcessEnv): TelemetryStatus;
+/**
+ * Best-effort enable hook. Always returns the sentinel
+ * `{ status: 'disabled', reason: ... }` payload. Reserved for v0.2+.
+ *
+ * @stable
+ */
+declare function enableTelemetry(): {
+  readonly status: 'disabled';
+  readonly reason: string;
+};
+/**
+ * Detect the reserved env vars and emit one informational line per
+ * process. Returns the lines as an array so callers can route them to
+ * any sink they like (defaults to `console.info`).
+ *
+ * @stable
+ */
+declare function announceTelemetryPosture(opts?: {
+  readonly env?: NodeJS.ProcessEnv;
+  readonly sink?: (line: string) => void;
+}): ReadonlyArray<string>;
+//#endregion
+export { TelemetryStatus, announceTelemetryPosture, enableTelemetry, getTelemetryStatus };
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/telemetry/index.ts"],"sourcesContent":[],"mappings":";;AAsBA;AAiBA;AAiBA;AAiBA;;;;;;;;;;;;;;;;;UAnDiB,eAAA;;;;;;;;;;;;;;;;iBAiBD,kBAAA,OAAwB,MAAA,CAAO,aAA2B;;;;;;;iBAiB1D,eAAA,CAAA;;;;;;;;;;;iBAiBA,wBAAA;iBACS,MAAA,CAAO;;IAC7B"}

package/dist/telemetry/index.js

@@ -0,0 +1,49 @@
+//#region src/telemetry/index.ts
+/**
+* Snapshot of the telemetry posture. Reads from `process.env` once
+* unless `env` is provided.
+*
+* @stable
+*/
+function getTelemetryStatus(env = process.env) {
+	const telemetry = env.GRAPHORIN_TELEMETRY;
+	const noPhoneHome = env.GRAPHORIN_NO_PHONE_HOME;
+	return {
+		enabled: false,
+		reason: "telemetry not yet implemented (v0.1 ships zero default telemetry)",
+		...telemetry === void 0 ? {} : { env: telemetry },
+		...noPhoneHome === void 0 ? {} : { noPhoneHome }
+	};
+}
+/**
+* Best-effort enable hook. Always returns the sentinel
+* `{ status: 'disabled', reason: ... }` payload. Reserved for v0.2+.
+*
+* @stable
+*/
+function enableTelemetry() {
+	return {
+		status: "disabled",
+		reason: "telemetry not yet implemented (v0.1 ships zero default telemetry)"
+	};
+}
+/**
+* Detect the reserved env vars and emit one informational line per
+* process. Returns the lines as an array so callers can route them to
+* any sink they like (defaults to `console.info`).
+*
+* @stable
+*/
+function announceTelemetryPosture(opts = {}) {
+	const env = opts.env ?? process.env;
+	const sink = opts.sink ?? ((line) => console.info(line));
+	const lines = [];
+	if (env.GRAPHORIN_TELEMETRY !== void 0) lines.push(`[graphorin/observability] info: GRAPHORIN_TELEMETRY=${env.GRAPHORIN_TELEMETRY} — acknowledged. Telemetry is hardcoded \`disabled\` in v0.1.`);
+	if (env.GRAPHORIN_NO_PHONE_HOME !== void 0) lines.push(`[graphorin/observability] info: GRAPHORIN_NO_PHONE_HOME=${env.GRAPHORIN_NO_PHONE_HOME} — acknowledged. Graphorin already makes zero outbound calls without explicit user action.`);
+	for (const line of lines) sink(line);
+	return lines;
+}
+
+//#endregion
+export { announceTelemetryPosture, enableTelemetry, getTelemetryStatus };
+//# sourceMappingURL=index.js.map

package/dist/telemetry/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["lines: string[]"],"sources":["../../src/telemetry/index.ts"],"sourcesContent":["/**\n * Zero-default telemetry stub.\n *\n * The framework promises to make zero outbound network calls without\n * an explicit user action. This module exists so consumers can:\n *\n * - inspect the telemetry posture from CLI / health endpoints,\n * - register the reserved `GRAPHORIN_TELEMETRY` / `GRAPHORIN_NO_PHONE_HOME`\n *   environment variables for forward compatibility,\n * - assert in tests that no implicit telemetry surface exists.\n *\n * Attempting to enable telemetry pre-v0.2 returns a sentinel result; it\n * never opens a socket.\n *\n * @packageDocumentation\n */\n\n/**\n * Result returned by {@link getTelemetryStatus}.\n *\n * @stable\n */\nexport interface TelemetryStatus {\n  /** Always `false` in v0.1. Reserved field. */\n  readonly enabled: false;\n  /** Plain-English explanation of the current state. */\n  readonly reason: string;\n  /** Resolved value of `GRAPHORIN_TELEMETRY` (if any). */\n  readonly env?: string;\n  /** Resolved value of `GRAPHORIN_NO_PHONE_HOME` (if any). */\n  readonly noPhoneHome?: string;\n}\n\n/**\n * Snapshot of the telemetry posture. Reads from `process.env` once\n * unless `env` is provided.\n *\n * @stable\n */\nexport function getTelemetryStatus(env: NodeJS.ProcessEnv = process.env): TelemetryStatus {\n  const telemetry = env.GRAPHORIN_TELEMETRY;\n  const noPhoneHome = env.GRAPHORIN_NO_PHONE_HOME;\n  return {\n    enabled: false,\n    reason: 'telemetry not yet implemented (v0.1 ships zero default telemetry)',\n    ...(telemetry === undefined ? {} : { env: telemetry }),\n    ...(noPhoneHome === undefined ? {} : { noPhoneHome }),\n  };\n}\n\n/**\n * Best-effort enable hook. Always returns the sentinel\n * `{ status: 'disabled', reason: ... }` payload. Reserved for v0.2+.\n *\n * @stable\n */\nexport function enableTelemetry(): {\n  readonly status: 'disabled';\n  readonly reason: string;\n} {\n  return {\n    status: 'disabled',\n    reason: 'telemetry not yet implemented (v0.1 ships zero default telemetry)',\n  };\n}\n\n/**\n * Detect the reserved env vars and emit one informational line per\n * process. Returns the lines as an array so callers can route them to\n * any sink they like (defaults to `console.info`).\n *\n * @stable\n */\nexport function announceTelemetryPosture(\n  opts: { readonly env?: NodeJS.ProcessEnv; readonly sink?: (line: string) => void } = {},\n): ReadonlyArray<string> {\n  const env = opts.env ?? process.env;\n  const sink = opts.sink ?? ((line: string) => console.info(line));\n  const lines: string[] = [];\n  if (env.GRAPHORIN_TELEMETRY !== undefined) {\n    lines.push(\n      `[graphorin/observability] info: GRAPHORIN_TELEMETRY=${env.GRAPHORIN_TELEMETRY} ` +\n        '— acknowledged. Telemetry is hardcoded `disabled` in v0.1.',\n    );\n  }\n  if (env.GRAPHORIN_NO_PHONE_HOME !== undefined) {\n    lines.push(\n      `[graphorin/observability] info: GRAPHORIN_NO_PHONE_HOME=${env.GRAPHORIN_NO_PHONE_HOME} ` +\n        '— acknowledged. Graphorin already makes zero outbound calls without explicit user action.',\n    );\n  }\n  for (const line of lines) sink(line);\n  return lines;\n}\n"],"mappings":";;;;;;;AAuCA,SAAgB,mBAAmB,MAAyB,QAAQ,KAAsB;CACxF,MAAM,YAAY,IAAI;CACtB,MAAM,cAAc,IAAI;AACxB,QAAO;EACL,SAAS;EACT,QAAQ;EACR,GAAI,cAAc,SAAY,EAAE,GAAG,EAAE,KAAK,WAAW;EACrD,GAAI,gBAAgB,SAAY,EAAE,GAAG,EAAE,aAAa;EACrD;;;;;;;;AASH,SAAgB,kBAGd;AACA,QAAO;EACL,QAAQ;EACR,QAAQ;EACT;;;;;;;;;AAUH,SAAgB,yBACd,OAAqF,EAAE,EAChE;CACvB,MAAM,MAAM,KAAK,OAAO,QAAQ;CAChC,MAAM,OAAO,KAAK,UAAU,SAAiB,QAAQ,KAAK,KAAK;CAC/D,MAAMA,QAAkB,EAAE;AAC1B,KAAI,IAAI,wBAAwB,OAC9B,OAAM,KACJ,uDAAuD,IAAI,oBAAoB,+DAEhF;AAEH,KAAI,IAAI,4BAA4B,OAClC,OAAM,KACJ,2DAA2D,IAAI,wBAAwB,4FAExF;AAEH,MAAK,MAAM,QAAQ,MAAO,MAAK,KAAK;AACpC,QAAO"}

package/dist/tracer/ids.d.ts

@@ -0,0 +1,23 @@
+//#region src/tracer/ids.d.ts
+/**
+ * Trace and span ID generators. The tracer prefers `crypto.randomUUID()`
+ * over a custom RNG for parity with the OpenTelemetry SDK behaviour and
+ * to avoid pulling another runtime dependency.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Generate a 32-hex-character (16-byte) trace id.
+ *
+ * @stable
+ */
+declare function newTraceId(): string;
+/**
+ * Generate a 16-hex-character (8-byte) span id.
+ *
+ * @stable
+ */
+declare function newSpanId(): string;
+//#endregion
+export { newSpanId, newTraceId };
+//# sourceMappingURL=ids.d.ts.map

package/dist/tracer/ids.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.d.ts","names":[],"sources":["../../src/tracer/ids.ts"],"sourcesContent":[],"mappings":";;AAeA;AASA;;;;;;;;;;iBATgB,UAAA,CAAA;;;;;;iBASA,SAAA,CAAA"}

package/dist/tracer/ids.js

@@ -0,0 +1,30 @@
+import { randomBytes } from "node:crypto";
+
+//#region src/tracer/ids.ts
+/**
+* Trace and span ID generators. The tracer prefers `crypto.randomUUID()`
+* over a custom RNG for parity with the OpenTelemetry SDK behaviour and
+* to avoid pulling another runtime dependency.
+*
+* @packageDocumentation
+*/
+/**
+* Generate a 32-hex-character (16-byte) trace id.
+*
+* @stable
+*/
+function newTraceId() {
+	return randomBytes(16).toString("hex");
+}
+/**
+* Generate a 16-hex-character (8-byte) span id.
+*
+* @stable
+*/
+function newSpanId() {
+	return randomBytes(8).toString("hex");
+}
+
+//#endregion
+export { newSpanId, newTraceId };
+//# sourceMappingURL=ids.js.map

package/dist/tracer/ids.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.js","names":[],"sources":["../../src/tracer/ids.ts"],"sourcesContent":["/**\n * Trace and span ID generators. The tracer prefers `crypto.randomUUID()`\n * over a custom RNG for parity with the OpenTelemetry SDK behaviour and\n * to avoid pulling another runtime dependency.\n *\n * @packageDocumentation\n */\n\nimport { randomBytes } from 'node:crypto';\n\n/**\n * Generate a 32-hex-character (16-byte) trace id.\n *\n * @stable\n */\nexport function newTraceId(): string {\n  return randomBytes(16).toString('hex');\n}\n\n/**\n * Generate a 16-hex-character (8-byte) span id.\n *\n * @stable\n */\nexport function newSpanId(): string {\n  return randomBytes(8).toString('hex');\n}\n"],"mappings":";;;;;;;;;;;;;;;AAeA,SAAgB,aAAqB;AACnC,QAAO,YAAY,GAAG,CAAC,SAAS,MAAM;;;;;;;AAQxC,SAAgB,YAAoB;AAClC,QAAO,YAAY,EAAE,CAAC,SAAS,MAAM"}

package/dist/tracer/index.d.ts

@@ -0,0 +1,6 @@
+import { newSpanId, newTraceId } from "./ids.js";
+import { Sampler, SamplingDecisionMaker, SamplingOptions, SamplingRule, createSampler } from "./sampling.js";
+import { GraphorinSpan, SetAttributeOptions } from "./span.js";
+import { spanNameFor } from "./span-names.js";
+import { GraphorinTracer, TracerOptions, asGraphorinSpan, createTracer } from "./tracer.js";
+export { type GraphorinSpan, type GraphorinTracer, type Sampler, type SamplingDecisionMaker, type SamplingOptions, type SamplingRule, type SetAttributeOptions, type TracerOptions, asGraphorinSpan, createSampler, createTracer, newSpanId, newTraceId, spanNameFor };

package/dist/tracer/index.js

@@ -0,0 +1,6 @@
+import { newSpanId, newTraceId } from "./ids.js";
+import { createSampler } from "./sampling.js";
+import { spanNameFor } from "./span-names.js";
+import { asGraphorinSpan, createTracer } from "./tracer.js";
+
+export { asGraphorinSpan, createSampler, createTracer, newSpanId, newTraceId, spanNameFor };

package/dist/tracer/sampling.d.ts

@@ -0,0 +1,77 @@
+import { SpanType } from "@graphorin/core";
+
+//#region src/tracer/sampling.d.ts
+
+/** @stable */
+type SamplingDecisionMaker = 'parent-based' | 'always-on' | 'rate-limit';
+/**
+ * Per-span-type rate override.
+ *
+ * @stable
+ */
+interface SamplingRule {
+  readonly type: SpanType | string;
+  readonly rate: number;
+}
+/**
+ * Configuration shape consumed by {@link createSampler}.
+ *
+ * @stable
+ */
+interface SamplingOptions {
+  /** Default head-sampling rate. Must be in `[0, 1]`. Defaults to `1.0`. */
+  readonly rate?: number;
+  /** Per-type overrides. Last write wins on duplicate `type`. */
+  readonly rules?: ReadonlyArray<SamplingRule>;
+  /** Decision maker. Defaults to `'parent-based'`. */
+  readonly decisionMaker?: SamplingDecisionMaker;
+  /**
+   * Cap for the `'rate-limit'` decision maker: at most this many root spans
+   * are sampled per rolling 1-second window (RP-19). `undefined` ⇒ no cap
+   * (samples everything); `0` ⇒ sample nothing. Ignored by the other
+   * decision makers.
+   */
+  readonly maxPerSecond?: number;
+  /**
+   * Clock for the `'rate-limit'` window. Defaults to `Date.now`.
+   *
+   * @internal
+   */
+  readonly now?: () => number;
+  /**
+   * Optional override for streaming-event sampling.
+   * @see RB-52 — streaming event family `tool.execute.{progress,partial}`.
+   */
+  readonly streaming?: {
+    readonly eventSamplingRate?: number;
+    readonly includeChunkContent?: 'none' | 'text-only' | 'all';
+  };
+  /**
+   * Override for the random source. Useful for deterministic tests.
+   *
+   * @internal
+   */
+  readonly random?: () => number;
+}
+/**
+ * @stable
+ */
+interface Sampler {
+  /** Decide whether a span of the given type should be recorded. */
+  shouldSample(type: SpanType | string, parentSampled?: boolean): boolean;
+  /** Decide whether a span event of the given name should be recorded. */
+  shouldRecordEvent(name: string): boolean;
+  /** Returns whether chunk *content* should travel through the exporter. */
+  shouldIncludeChunkContent(): boolean;
+}
+/**
+ * Build a {@link Sampler} from the supplied options. The sampler is
+ * intentionally inexpensive — every decision boils down to a single
+ * `random < threshold` comparison.
+ *
+ * @stable
+ */
+declare function createSampler(opts?: SamplingOptions): Sampler;
+//#endregion
+export { Sampler, SamplingDecisionMaker, SamplingOptions, SamplingRule, createSampler };
+//# sourceMappingURL=sampling.d.ts.map

package/dist/tracer/sampling.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampling.d.ts","names":[],"sources":["../../src/tracer/sampling.ts"],"sourcesContent":[],"mappings":";;;;;AAoEiB,KAxDL,qBAAA,GA0DiB,cAAA,GAAA,WAAA,GAAA,YAAA;AAc7B;;;;;UAjEiB,YAAA;iBACA;;;;;;;;UASA,eAAA;;;;mBAIE,cAAc;;2BAEN;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAiCV,OAAA;;qBAEI;;;;;;;;;;;;;iBAcL,aAAA,QAAoB,kBAAuB"}

package/dist/tracer/sampling.js

@@ -0,0 +1,67 @@
+//#region src/tracer/sampling.ts
+/**
+* Build a {@link Sampler} from the supplied options. The sampler is
+* intentionally inexpensive — every decision boils down to a single
+* `random < threshold` comparison.
+*
+* @stable
+*/
+function createSampler(opts = {}) {
+	const baseRate = clampRate(opts.rate ?? 1);
+	const decisionMaker = opts.decisionMaker ?? "parent-based";
+	const ruleByType = /* @__PURE__ */ new Map();
+	for (const rule of opts.rules ?? []) ruleByType.set(rule.type, clampRate(rule.rate));
+	const streamingRate = clampRate(opts.streaming?.eventSamplingRate ?? 1);
+	const includeChunks = opts.streaming?.includeChunkContent ?? "none";
+	const random = opts.random ?? Math.random;
+	const maxPerSecond = opts.maxPerSecond;
+	const now = opts.now ?? Date.now;
+	let windowStart;
+	let windowCount = 0;
+	return {
+		shouldSample(type, parentSampled) {
+			if (decisionMaker === "always-on") return true;
+			if (decisionMaker === "parent-based") {
+				if (parentSampled === true) return true;
+				if (parentSampled === false) return false;
+			}
+			if (decisionMaker === "rate-limit") {
+				if (maxPerSecond === void 0) return true;
+				if (maxPerSecond <= 0) return false;
+				const t = now();
+				if (windowStart === void 0 || t - windowStart >= 1e3) {
+					windowStart = t;
+					windowCount = 0;
+				}
+				if (windowCount < maxPerSecond) {
+					windowCount += 1;
+					return true;
+				}
+				return false;
+			}
+			const rate = ruleByType.get(type) ?? baseRate;
+			if (rate >= 1) return true;
+			if (rate <= 0) return false;
+			return random() < rate;
+		},
+		shouldRecordEvent(name) {
+			const rate = ruleByType.get(name) ?? streamingRate;
+			if (rate >= 1) return true;
+			if (rate <= 0) return false;
+			return random() < rate;
+		},
+		shouldIncludeChunkContent() {
+			return includeChunks !== "none";
+		}
+	};
+}
+function clampRate(rate) {
+	if (Number.isNaN(rate)) return 1;
+	if (rate < 0) return 0;
+	if (rate > 1) return 1;
+	return rate;
+}
+
+//#endregion
+export { createSampler };
+//# sourceMappingURL=sampling.js.map