@contractspec/lib.contracts 0.0.0-canary-20260113162409

package/dist/server/rest-generic.js

@@ -0,0 +1,124 @@
+import { defaultRestPath } from "../jsonschema.js";
+
+//#region src/server/rest-generic.ts
+/** Minimal WHATWG Response polyfill util for Node < 18 (if needed) */
+function corsHeaders(opt) {
+	const h = {};
+	h["access-control-allow-origin"] = typeof opt === "object" ? opt.origin ?? "*" : "*";
+	h["vary"] = "Origin";
+	if (typeof opt === "object") {
+		if (opt.methods) h["access-control-allow-methods"] = opt.methods.join(", ");
+		if (opt.headers) h["access-control-allow-headers"] = opt.headers.join(", ");
+		if (opt.credentials) h["access-control-allow-credentials"] = "true";
+		if (typeof opt.maxAge === "number") h["access-control-max-age"] = String(opt.maxAge);
+	} else {
+		h["access-control-allow-methods"] = "GET,POST,OPTIONS";
+		h["access-control-allow-headers"] = "content-type,x-idempotency-key,x-trace-id";
+	}
+	return h;
+}
+function joinPath(a, b) {
+	return `${(a ?? "").replace(/\/+$/g, "")}/${b.replace(/^\/+/g, "")}`.replace(/\/{2,}/g, "/");
+}
+/**
+* Build a single Fetch-style handler: (req) => Response
+* - Discovers routes from OperationSpecRegistry
+* - Validates with zod via registry.execute()
+* - Handles CORS (optional)
+*/
+function createFetchHandler(reg, ctxFactory, options) {
+	const opts = {
+		basePath: options?.basePath ?? "",
+		cors: options?.cors ?? false,
+		prettyJson: options?.prettyJson ?? false,
+		onError: options?.onError
+	};
+	const routes = reg.list().map((spec) => ({
+		method: spec.transport?.rest?.method ?? (spec.meta.kind === "query" ? "GET" : "POST"),
+		path: joinPath(opts.basePath, spec.transport?.rest?.path ?? defaultRestPath(spec.meta.key, spec.meta.version)),
+		name: spec.meta.key,
+		version: spec.meta.version
+	}));
+	const routeTable = /* @__PURE__ */ new Map();
+	for (const r of routes) routeTable.set(`${r.method} ${r.path}`, r);
+	const makeJson = (status, data, extraHeaders) => {
+		const body = opts.prettyJson ? JSON.stringify(data, null, opts.prettyJson) : JSON.stringify(data);
+		const base = { "content-type": "application/json; charset=utf-8" };
+		return new Response(body, {
+			status,
+			headers: extraHeaders ? {
+				...base,
+				...extraHeaders
+			} : base
+		});
+	};
+	return async function handle(req) {
+		const url = new URL(req.url);
+		const key = `${req.method.toUpperCase()} ${url.pathname}`;
+		if (opts.cors && req.method.toUpperCase() === "OPTIONS") {
+			const h = corsHeaders(opts.cors === true ? {} : opts.cors);
+			return new Response(null, {
+				status: 204,
+				headers: {
+					...h,
+					"content-length": "0"
+				}
+			});
+		}
+		const route = routeTable.get(key);
+		if (!route) {
+			const headers = {};
+			if (opts.cors) Object.assign(headers, corsHeaders(opts.cors === true ? {} : opts.cors));
+			return makeJson(404, {
+				error: "NotFound",
+				path: url.pathname
+			}, headers);
+		}
+		try {
+			let input = {};
+			if (route.method === "GET") if (url.searchParams.has("input")) {
+				const raw = url.searchParams.get("input");
+				input = raw ? JSON.parse(raw) : {};
+			} else {
+				const obj = {};
+				for (const [k, v] of url.searchParams.entries()) obj[k] = v;
+				input = obj;
+			}
+			else {
+				const contentType = req.headers.get("content-type") || "";
+				if (contentType.includes("application/json")) input = await req.json();
+				else if (contentType.includes("application/x-www-form-urlencoded")) {
+					const form = await req.formData();
+					input = Object.fromEntries(form.entries());
+				} else if (!contentType) input = {};
+				else return makeJson(415, {
+					error: "UnsupportedMediaType",
+					contentType
+				});
+			}
+			const ctx = ctxFactory(req);
+			const result = await reg.execute(route.name, route.version, input, ctx);
+			const headers = {};
+			if (opts.cors) Object.assign(headers, corsHeaders(opts.cors === true ? {} : opts.cors));
+			return makeJson(200, result, headers);
+		} catch (err) {
+			if (opts.onError) {
+				const mapped = opts.onError(err);
+				const headers$1 = {};
+				if (opts.cors) Object.assign(headers$1, corsHeaders(opts.cors === true ? {} : opts.cors));
+				return makeJson(mapped.status, mapped.body, headers$1);
+			}
+			const headers = {};
+			if (opts.cors) Object.assign(headers, corsHeaders(opts.cors === true ? {} : opts.cors));
+			if (err?.issues) return makeJson(400, {
+				error: "ValidationError",
+				issues: err.issues
+			}, headers);
+			if (typeof err?.message === "string" && err.message.startsWith("PolicyDenied")) return makeJson(403, { error: "PolicyDenied" }, headers);
+			return makeJson(500, { error: "InternalError" }, headers);
+		}
+	};
+}
+
+//#endregion
+export { createFetchHandler };

package/dist/server/rest-next-app.d.ts

@@ -0,0 +1,35 @@
+import { OperationSpecRegistry } from "../operations/registry.js";
+import { HandlerCtx } from "../types.js";
+import { RestOptions } from "./rest-generic.js";
+
+//#region src/server/rest-next-app.d.ts
+
+/**
+ * Creates a Next.js App Router route handler for ContractSpec operations.
+ *
+ * This function returns a handler suitable for `export const { GET, POST }` in a `route.ts` file.
+ * It handles:
+ * - Path parsing to determine the operation name and version.
+ * - Body parsing (JSON).
+ * - Context creation via `ctxFactory`.
+ * - Execution via `OperationSpecRegistry`.
+ * - Response formatting (JSON success/error).
+ *
+ * @param reg - The OperationSpecRegistry containing the operations.
+ * @param ctxFactory - A factory function to build the `HandlerCtx` (e.g., auth, tenant) from the request.
+ * @param options - Optional configuration for the REST handler.
+ * @returns A function `(req: Request) => Promise<Response>`.
+ *
+ * @example
+ * ```ts
+ * // app/api/[...route]/route.ts
+ * import { makeNextAppHandler } from '@contractspec/lib.contracts/server/rest-next-app';
+ * import { registry } from '@/lib/registry';
+ *
+ * const handler = makeNextAppHandler(registry, (req) => ({ actor: 'anonymous' }));
+ * export { handler as GET, handler as POST };
+ * ```
+ */
+declare function makeNextAppHandler(reg: OperationSpecRegistry, ctxFactory: (req: Request) => HandlerCtx, options?: RestOptions): (req: Request) => Promise<Response>;
+//#endregion
+export { makeNextAppHandler };

package/dist/server/rest-next-app.js

@@ -0,0 +1,38 @@
+import { createFetchHandler } from "./rest-generic.js";
+
+//#region src/server/rest-next-app.ts
+/**
+* Creates a Next.js App Router route handler for ContractSpec operations.
+*
+* This function returns a handler suitable for `export const { GET, POST }` in a `route.ts` file.
+* It handles:
+* - Path parsing to determine the operation name and version.
+* - Body parsing (JSON).
+* - Context creation via `ctxFactory`.
+* - Execution via `OperationSpecRegistry`.
+* - Response formatting (JSON success/error).
+*
+* @param reg - The OperationSpecRegistry containing the operations.
+* @param ctxFactory - A factory function to build the `HandlerCtx` (e.g., auth, tenant) from the request.
+* @param options - Optional configuration for the REST handler.
+* @returns A function `(req: Request) => Promise<Response>`.
+*
+* @example
+* ```ts
+* // app/api/[...route]/route.ts
+* import { makeNextAppHandler } from '@contractspec/lib.contracts/server/rest-next-app';
+* import { registry } from '@/lib/registry';
+*
+* const handler = makeNextAppHandler(registry, (req) => ({ actor: 'anonymous' }));
+* export { handler as GET, handler as POST };
+* ```
+*/
+function makeNextAppHandler(reg, ctxFactory, options) {
+	const handler = createFetchHandler(reg, ctxFactory, options);
+	return async function requestHandler(req) {
+		return handler(req);
+	};
+}
+
+//#endregion
+export { makeNextAppHandler };

package/dist/server/rest-next-mcp.d.ts

@@ -0,0 +1,11 @@
+import { OperationSpecRegistry } from "../operations/registry.js";
+import { HandlerCtx } from "../types.js";
+
+//#region src/server/rest-next-mcp.d.ts
+declare function makeNextMcpServerFromRegistry(reg: OperationSpecRegistry, ctxFactory: () => HandlerCtx): {
+  GET: (request: Request) => Promise<Response>;
+  POST: (request: Request) => Promise<Response>;
+  DELETE: (request: Request) => Promise<Response>;
+};
+//#endregion
+export { makeNextMcpServerFromRegistry };

package/dist/server/rest-next-mcp.js

@@ -0,0 +1,45 @@
+import { defaultMcpTool, jsonSchemaForSpec } from "../jsonschema.js";
+import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { createMcpHandler } from "mcp-handler";
+
+//#region src/server/rest-next-mcp.ts
+function makeNextMcpServerFromRegistry(reg, ctxFactory) {
+	const handler = createMcpHandler((server) => {
+		for (const spec of reg.list()) {
+			const { input, meta } = jsonSchemaForSpec(spec);
+			if (meta.kind === "query") {
+				const resourceName = spec.transport?.mcp?.toolName ?? defaultMcpTool(spec.meta.key, spec.meta.version);
+				server.registerResource(resourceName, new ResourceTemplate("users://{userId}/profile", { list: void 0 }), {
+					description: spec.meta.description,
+					inputSchema: input
+				}, (async (uri, args, _req) => {
+					const result = await reg.execute(spec.meta.key, spec.meta.version, args ?? {}, ctxFactory());
+					return { contents: [{
+						uri: uri.href,
+						text: String(result)
+					}] };
+				}));
+			} else if (meta.kind === "command") {
+				const toolName = spec.transport?.mcp?.toolName ?? defaultMcpTool(spec.meta.key, spec.meta.version);
+				server.registerTool(toolName, {
+					description: spec.meta.description,
+					inputSchema: input
+				}, (async (args, _req) => {
+					const result = await reg.execute(spec.meta.key, spec.meta.version, args ?? {}, ctxFactory());
+					return { content: [{
+						type: "text",
+						text: String(result)
+					}] };
+				}));
+			} else throw new Error(`Unsupported kind: ${meta.kind}`);
+		}
+	}, {}, { basePath: "/api" });
+	return {
+		GET: handler,
+		POST: handler,
+		DELETE: handler
+	};
+}
+
+//#endregion
+export { makeNextMcpServerFromRegistry };

package/dist/server/rest-next-pages.d.ts

@@ -0,0 +1,9 @@
+import { OperationSpecRegistry } from "../operations/registry.js";
+import { HandlerCtx } from "../types.js";
+import { RestOptions } from "./rest-generic.js";
+import { NextApiRequest, NextApiResponse } from "next";
+
+//#region src/server/rest-next-pages.d.ts
+declare function makeNextPagesHandler(reg: OperationSpecRegistry, ctxFactory: (req: NextApiRequest) => HandlerCtx, options?: RestOptions): (req: NextApiRequest, res: NextApiResponse) => Promise<void>;
+//#endregion
+export { makeNextPagesHandler };

package/dist/server/rest-next-pages.js

@@ -0,0 +1,22 @@
+import { createFetchHandler } from "./rest-generic.js";
+
+//#region src/server/rest-next-pages.ts
+function makeNextPagesHandler(reg, ctxFactory, options) {
+	return async function handler(req, res) {
+		const url = `${req.headers["x-forwarded-proto"] ?? "http"}://${req.headers.host}${req.url}`;
+		const method = req.method?.toUpperCase() || "GET";
+		const request = new Request(url, {
+			method,
+			headers: Object.fromEntries(Object.entries(req.headers).map(([k, v]) => [k, String(v)])),
+			body: method === "POST" ? JSON.stringify(req.body ?? {}) : void 0
+		});
+		const response = await createFetchHandler(reg, () => ctxFactory(req), options)(request);
+		res.status(response.status);
+		response.headers.forEach((v, k) => res.setHeader(k, v));
+		const text = await response.text();
+		res.send(text);
+	};
+}
+
+//#endregion
+export { makeNextPagesHandler };

package/dist/telemetry/anomaly.d.ts

@@ -0,0 +1,27 @@
+import { TelemetryAnomalyDetectionConfig } from "./spec.js";
+import { TelemetryDispatch } from "./tracker.js";
+
+//#region src/telemetry/anomaly.d.ts
+interface TelemetryAnomalyEvent {
+  dispatch: TelemetryDispatch;
+  threshold: TelemetryAnomalyDetectionConfig;
+  metric: string;
+  value: number | undefined;
+  type: 'min' | 'max';
+}
+interface TelemetryAnomalyMonitorOptions {
+  onAnomaly?: (event: TelemetryAnomalyEvent) => void;
+  now?: () => Date;
+}
+declare class TelemetryAnomalyMonitor {
+  private readonly onAnomaly?;
+  private readonly now;
+  private readonly samples;
+  constructor(options?: TelemetryAnomalyMonitorOptions);
+  observe(dispatch: TelemetryDispatch): void;
+  private extractMetric;
+  private emit;
+  reset(): void;
+}
+//#endregion
+export { TelemetryAnomalyEvent, TelemetryAnomalyMonitor, TelemetryAnomalyMonitorOptions };

package/dist/telemetry/anomaly.js

@@ -0,0 +1,48 @@
+//#region src/telemetry/anomaly.ts
+var TelemetryAnomalyMonitor = class {
+	onAnomaly;
+	now;
+	samples = /* @__PURE__ */ new Map();
+	constructor(options = {}) {
+		this.onAnomaly = options.onAnomaly;
+		this.now = options.now ?? (() => /* @__PURE__ */ new Date());
+	}
+	observe(dispatch) {
+		const anomalyConfig = dispatch.definition.anomalyDetection;
+		if (!anomalyConfig?.enabled) return;
+		if (!anomalyConfig.thresholds?.length) return;
+		const eventKey = `${dispatch.name}.v${dispatch.version}`;
+		const newCount = (this.samples.get(eventKey) ?? 0) + 1;
+		this.samples.set(eventKey, newCount);
+		if (typeof anomalyConfig.minimumSample === "number" && newCount < anomalyConfig.minimumSample) return;
+		for (const threshold of anomalyConfig.thresholds) {
+			const value = this.extractMetric(dispatch, threshold.metric);
+			if (typeof value !== "number") continue;
+			if (typeof threshold.min === "number" && value < threshold.min) this.emit(dispatch, anomalyConfig, threshold.metric, value, "min");
+			if (typeof threshold.max === "number" && value > threshold.max) this.emit(dispatch, anomalyConfig, threshold.metric, value, "max");
+		}
+	}
+	extractMetric(dispatch, metric) {
+		const value = dispatch.properties[metric];
+		if (typeof value === "number") return value;
+		if (typeof value === "object" && value !== null && "value" in value) {
+			const maybeNumber = value.value;
+			return typeof maybeNumber === "number" ? maybeNumber : void 0;
+		}
+	}
+	emit(dispatch, threshold, metric, value, type) {
+		this.onAnomaly?.({
+			dispatch,
+			threshold,
+			metric,
+			value,
+			type
+		});
+	}
+	reset() {
+		this.samples.clear();
+	}
+};
+
+//#endregion
+export { TelemetryAnomalyMonitor };

package/dist/telemetry/docs/telemetry.docblock.d.ts

@@ -0,0 +1,6 @@
+import { DocBlock } from "@contractspec/lib.contracts/docs";
+
+//#region src/telemetry/docs/telemetry.docblock.d.ts
+declare const tech_contracts_telemetry_DocBlocks: DocBlock[];
+//#endregion
+export { tech_contracts_telemetry_DocBlocks };

package/dist/telemetry/docs/telemetry.docblock.js

@@ -0,0 +1,21 @@
+import { registerDocBlocks } from "../../docs/registry.js";
+
+//#region src/telemetry/docs/telemetry.docblock.ts
+const tech_contracts_telemetry_DocBlocks = [{
+	id: "docs.tech.contracts.telemetry",
+	title: "TelemetrySpec",
+	summary: "Telemetry specs describe product analytics in a durable, type-safe way. They reference existing `EventSpec`s (same name/version) but layer on privacy classification, retention, sampling, and anomaly detection so instrumentation stays compliant and observable.",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/contracts/telemetry",
+	tags: [
+		"tech",
+		"contracts",
+		"telemetry"
+	],
+	body: "## TelemetrySpec\n\nTelemetry specs describe product analytics in a durable, type-safe way. They reference existing `EventSpec`s (same name/version) but layer on privacy classification, retention, sampling, and anomaly detection so instrumentation stays compliant and observable.\n\n- **File location**: `packages/libs/contracts/src/telemetry/spec.ts`\n- **Runtime tracker**: `packages/libs/contracts/src/telemetry/tracker.ts`\n- **Anomaly monitor**: `packages/libs/contracts/src/telemetry/anomaly.ts`\n\n### Core concepts\n\n```ts\nexport interface TelemetrySpec {\n  meta: TelemetryMeta;\n  events: TelemetryEventDef[];\n  config?: TelemetryConfig;\n}\n```\n\n- `meta`: ownership + identifiers (`name`, `version`, `domain`)\n- `events`: per-event semantics, property definitions, privacy level, retention, sampling, anomaly rules\n- `config`: defaults and provider configuration\n- `TelemetryRegistry`: registers specs, resolves latest version, finds event definitions by name/version\n\n### An example\n\n```ts\nexport const SigilTelemetry: TelemetrySpec = {\n  meta: {\n    name: 'sigil.telemetry',\n    version: '1.0.0',\n    title: 'Sigil telemetry',\n    description: 'Core Sigil product telemetry',\n    domain: 'sigil',\n    owners: ['@team.analytics'],\n    tags: ['telemetry'],\n    stability: StabilityEnum.Experimental,\n  },\n  config: {\n    defaultRetentionDays: 30,\n    defaultSamplingRate: 1,\n    providers: [\n      { type: 'posthog', config: { projectApiKey: process.env.POSTHOG_KEY } },\n    ],\n  },\n  events: [\n    {\n      name: 'sigil.telemetry.workflow_step',\n      version: '1.0.0',\n      semantics: {\n        what: 'Workflow step executed',\n        who: 'Actor executing the workflow',\n      },\n      privacy: 'internal',\n      properties: {\n        workflow: { type: 'string', required: true },\n        step: { type: 'string', required: true },\n        durationMs: { type: 'number' },\n        userId: { type: 'string', pii: true, redact: true },\n      },\n      anomalyDetection: {\n        enabled: true,\n        minimumSample: 10,\n        thresholds: [\n          { metric: 'durationMs', max: 1500 },\n        ],\n        actions: ['alert', 'trigger_regen'],\n      },\n    },\n  ],\n};\n```\n\n### Tracking events at runtime\n\n`TelemetryTracker` performs sampling, PII redaction, provider dispatch, and anomaly detection.\n\n```ts\nconst tracker = new TelemetryTracker({\n  registry: telemetryRegistry,\n  providers: [\n    {\n      id: 'posthog',\n      async send(dispatch) {\n        posthog.capture({\n          event: dispatch.name,\n          properties: dispatch.properties,\n          distinctId: dispatch.context.userId ?? dispatch.context.sessionId,\n        });\n      },\n    },\n  ],\n  anomalyMonitor: new TelemetryAnomalyMonitor({\n    onAnomaly(event) {\n      console.warn('Telemetry anomaly detected', event);\n    },\n  }),\n});\n\nawait tracker.track('sigil.telemetry.workflow_step', 1, {\n  workflow: 'onboarding',\n  step: 'verify_email',\n  durationMs: 2100,\n  userId: 'user-123',\n});\n```\n\n- Sampling obeys the event-specific rate (fallback to spec defaults)\n- Properties flagged with `pii` or `redact` are masked before dispatch\n- Anomaly monitor evaluates thresholds and triggers actions (e.g., log, alert, regeneration)\n\n### Spec integration\n\n- `ContractSpec.telemetry` allows operations to emit success/failure events automatically\n- `OperationSpecRegistry.execute()` uses the tracker when `ctx.telemetry` is provided\n- `WorkflowRunner` (Phase 4 follow-up) will emit telemetry during step transitions\n- `TelemetrySpec` events should reuse `EventSpec` names/versions to keep analytics/contract parity\n\n### CLI workflow\n\n```\ncontracts-cli create telemetry\n```\n\n- Interactive wizard prompts for meta, providers, events, properties, retention, anomaly rules\n- Output: `*.telemetry.ts` file using `TelemetrySpec`\n\n### Best practices\n\n- Prefer `internal` privacy for non-PII; mark PII properties explicitly with `pii` + `redact`\n- Keep sampling ≥0.05 except for high-volume events\n- Configure anomaly detection on key metrics (duration, error count, conversion)\n- Check telemetry into source control alongside contracts; regenerate via CLI when specs change\n\n### Next steps\n\n- Phase 5: Regenerator monitors telemetry anomalies to propose spec improvements\n- Phase 6: Studio surfaces telemetry controls per tenant via `TenantAppConfig`\n\n"
+}];
+registerDocBlocks(tech_contracts_telemetry_DocBlocks);
+
+//#endregion
+export { tech_contracts_telemetry_DocBlocks };

package/dist/telemetry/index.d.ts

@@ -0,0 +1,4 @@
+import { TelemetryAnomalyAction, TelemetryAnomalyDetectionConfig, TelemetryAnomalyThreshold, TelemetryConfig, TelemetryEventDef, TelemetryMeta, TelemetryPrivacyLevel, TelemetryPropertyDef, TelemetryProviderConfig, TelemetryRegistry, TelemetryRetentionConfig, TelemetrySamplingConfig, TelemetrySpec, makeTelemetryKey } from "./spec.js";
+import { TelemetryAnomalyEvent, TelemetryAnomalyMonitor, TelemetryAnomalyMonitorOptions } from "./anomaly.js";
+import { RuntimeTelemetryProvider, TelemetryDispatch, TelemetryEventContext, TelemetryTracker, TelemetryTrackerOptions } from "./tracker.js";
+export { RuntimeTelemetryProvider, TelemetryAnomalyAction, TelemetryAnomalyDetectionConfig, TelemetryAnomalyEvent, TelemetryAnomalyMonitor, TelemetryAnomalyMonitorOptions, TelemetryAnomalyThreshold, TelemetryConfig, TelemetryDispatch, TelemetryEventContext, TelemetryEventDef, TelemetryMeta, TelemetryPrivacyLevel, TelemetryPropertyDef, TelemetryProviderConfig, TelemetryRegistry, TelemetryRetentionConfig, TelemetrySamplingConfig, TelemetrySpec, TelemetryTracker, TelemetryTrackerOptions, makeTelemetryKey };

package/dist/telemetry/index.js

@@ -0,0 +1,5 @@
+import { TelemetryRegistry, makeTelemetryKey } from "./spec.js";
+import { TelemetryTracker } from "./tracker.js";
+import { TelemetryAnomalyMonitor } from "./anomaly.js";
+
+export { TelemetryAnomalyMonitor, TelemetryRegistry, TelemetryTracker, makeTelemetryKey };

package/dist/telemetry/spec.d.ts

@@ -0,0 +1,91 @@
+import { OwnerShipMeta } from "../ownership.js";
+import { SpecContractRegistry } from "../registry.js";
+
+//#region src/telemetry/spec.d.ts
+type TelemetryPrivacyLevel = 'public' | 'internal' | 'pii' | 'sensitive';
+type TelemetryMeta = OwnerShipMeta;
+interface TelemetryPropertyDef {
+  type: 'string' | 'number' | 'boolean' | 'timestamp' | 'json';
+  required?: boolean;
+  pii?: boolean;
+  redact?: boolean;
+  description?: string;
+}
+interface TelemetryAnomalyThreshold {
+  metric: string;
+  min?: number;
+  max?: number;
+}
+type TelemetryAnomalyAction = 'alert' | 'log' | 'trigger_regen';
+interface TelemetryAnomalyDetectionConfig {
+  enabled: boolean;
+  thresholds?: TelemetryAnomalyThreshold[];
+  actions?: TelemetryAnomalyAction[];
+  /**
+   * Minimum sample size before evaluating thresholds.
+   * Helps avoid false positives on small sample sizes.
+   */
+  minimumSample?: number;
+}
+interface TelemetrySamplingConfig {
+  rate: number;
+  conditions?: string[];
+}
+interface TelemetryRetentionConfig {
+  days: number;
+  policy?: 'archive' | 'delete';
+}
+interface TelemetryEventDef {
+  /** Name of the event (should match EventSpec.key for cross-reference). */
+  key: string;
+  /** Version of the underlying event. */
+  version: string;
+  /** High-level semantics for docs/analyzers. */
+  semantics: {
+    who?: string;
+    what: string;
+    why?: string;
+  };
+  /** Detailed property metadata keyed by property name. */
+  properties: Record<string, TelemetryPropertyDef>;
+  /** Privacy level for the entire event. */
+  privacy: TelemetryPrivacyLevel;
+  /** Retention policy overrides. */
+  retention?: TelemetryRetentionConfig;
+  /** Sampling rules, defaulting to spec.config defaults. */
+  sampling?: TelemetrySamplingConfig;
+  /** Anomaly detection overrides. */
+  anomalyDetection?: TelemetryAnomalyDetectionConfig;
+  /** Optional tags for analytics/AI hints. */
+  tags?: string[];
+}
+interface TelemetryProviderConfig {
+  type: 'posthog' | 'segment' | 'opentelemetry' | 'internal';
+  config: Record<string, unknown>;
+}
+interface TelemetryConfig {
+  defaultRetentionDays?: number;
+  defaultSamplingRate?: number;
+  providers?: TelemetryProviderConfig[];
+  anomalyDetection?: {
+    enabled: boolean;
+    checkIntervalMs?: number;
+  };
+}
+interface TelemetrySpec {
+  meta: TelemetryMeta;
+  events: TelemetryEventDef[];
+  config?: TelemetryConfig;
+}
+declare class TelemetryRegistry extends SpecContractRegistry<'telemetry', TelemetrySpec> {
+  private readonly eventsByKey;
+  private readonly specByEventKey;
+  constructor(items?: TelemetrySpec[]);
+  register(spec: TelemetrySpec): this;
+  private indexEvents;
+  findEventDef(name: string, version?: string): TelemetryEventDef | undefined;
+  getSpecForEvent(name: string, version: string): TelemetrySpec | undefined;
+}
+declare function makeTelemetryKey(meta: TelemetryMeta): string;
+//#endregion
+export { TelemetryAnomalyAction, TelemetryAnomalyDetectionConfig, TelemetryAnomalyThreshold, TelemetryConfig, TelemetryEventDef, TelemetryMeta, TelemetryPrivacyLevel, TelemetryPropertyDef, TelemetryProviderConfig, TelemetryRegistry, TelemetryRetentionConfig, TelemetrySamplingConfig, TelemetrySpec, makeTelemetryKey };

package/dist/telemetry/spec.js

@@ -0,0 +1,42 @@
+import { SpecContractRegistry } from "../registry.js";
+import { compareVersions } from "compare-versions";
+
+//#region src/telemetry/spec.ts
+const telemetryKey = (meta) => `${meta.key}.v${meta.version}`;
+var TelemetryRegistry = class extends SpecContractRegistry {
+	eventsByKey = /* @__PURE__ */ new Map();
+	specByEventKey = /* @__PURE__ */ new Map();
+	constructor(items) {
+		super("telemetry", items);
+		if (items) items.forEach((spec) => this.indexEvents(spec));
+	}
+	register(spec) {
+		super.register(spec);
+		this.indexEvents(spec);
+		return this;
+	}
+	indexEvents(spec) {
+		for (const event of spec.events) {
+			this.eventsByKey.set(`${event.key}.v${event.version}`, event);
+			this.specByEventKey.set(`${event.key}.v${event.version}`, spec);
+		}
+	}
+	findEventDef(name, version) {
+		if (version != null) return this.eventsByKey.get(`${name}.v${version}`);
+		let latest;
+		for (const event of this.eventsByKey.values()) {
+			if (event.key !== name) continue;
+			if (!latest || compareVersions(event.version, latest.version) > 0) latest = event;
+		}
+		return latest;
+	}
+	getSpecForEvent(name, version) {
+		return this.specByEventKey.get(`${name}.v${version}`);
+	}
+};
+function makeTelemetryKey(meta) {
+	return telemetryKey(meta);
+}
+
+//#endregion
+export { TelemetryRegistry, makeTelemetryKey };

package/dist/telemetry/tracker.d.ts

@@ -0,0 +1,51 @@
+import { TelemetryEventDef, TelemetryRegistry, TelemetrySpec } from "./spec.js";
+import { TelemetryAnomalyMonitor } from "./anomaly.js";
+
+//#region src/telemetry/tracker.d.ts
+interface TelemetryEventContext {
+  tenantId?: string;
+  organizationId?: string | null;
+  userId?: string | null;
+  sessionId?: string | null;
+  actor?: 'anonymous' | 'user' | 'admin';
+  channel?: 'web' | 'mobile' | 'job' | 'agent';
+  metadata?: Record<string, unknown>;
+}
+interface TelemetryDispatch {
+  id: string;
+  name: string;
+  version: string;
+  occurredAt: string;
+  properties: Record<string, unknown>;
+  privacy: TelemetryEventDef['privacy'];
+  context: TelemetryEventContext;
+  tags?: string[];
+  spec: TelemetrySpec;
+  definition: TelemetryEventDef;
+}
+interface RuntimeTelemetryProvider {
+  id: string;
+  send(event: TelemetryDispatch): Promise<void>;
+}
+interface TelemetryTrackerOptions {
+  registry: TelemetryRegistry;
+  providers?: RuntimeTelemetryProvider[];
+  anomalyMonitor?: TelemetryAnomalyMonitor;
+  random?: () => number;
+  clock?: () => Date;
+}
+declare class TelemetryTracker {
+  private readonly providers;
+  private readonly registry;
+  private readonly anomalyMonitor?;
+  private readonly random;
+  private readonly clock;
+  constructor(options: TelemetryTrackerOptions);
+  registerProvider(provider: RuntimeTelemetryProvider): void;
+  unregisterProvider(providerId: string): void;
+  track(name: string, version: string, properties: Record<string, unknown>, context?: TelemetryEventContext): Promise<boolean>;
+  private shouldSample;
+  private redactProperties;
+}
+//#endregion
+export { RuntimeTelemetryProvider, TelemetryDispatch, TelemetryEventContext, TelemetryTracker, TelemetryTrackerOptions };