@lssm/lib.contracts 1.41.1 → 1.42.1

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

@@ -1 +1,45 @@
-import{defaultMcpTool as e,jsonSchemaForSpec as t}from"../jsonschema.js";import{ResourceTemplate as n}from"@modelcontextprotocol/sdk/server/mcp.js";import{createMcpHandler as r}from"mcp-handler";function i(i,a){let o=r(r=>{for(let o of i.listSpecs()){let{input:s,output:c,meta:l}=t(o);if(l.kind===`query`){let t=o.transport?.mcp?.toolName??e(o.meta.name,o.meta.version);r.registerResource(t,new n(`users://{userId}/profile`,{list:void 0}),{description:o.meta.description,inputSchema:s},(async(e,t,n)=>{let r=await i.execute(o.meta.name,o.meta.version,t??{},a());return{contents:[{uri:e.href,text:String(r)}]}}))}else if(l.kind===`command`){let t=o.transport?.mcp?.toolName??e(o.meta.name,o.meta.version);r.registerTool(t,{description:o.meta.description,inputSchema:s},(async(e,t)=>{let n=await i.execute(o.meta.name,o.meta.version,e??{},a());return{content:[{type:`text`,text:String(n)}]}}))}else throw Error(`Unsupported kind: ${l.kind}`)}},{},{basePath:`/api`});return{GET:o,POST:o,DELETE:o}}export{i as makeNextMcpServerFromRegistry};
+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.listSpecs()) {
+			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 { HandlerCtx } from "../types.js";
+import { OperationSpecRegistry } from "../operations/registry.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

@@ -1 +1,22 @@
-import{createFetchHandler as e}from"./rest-generic.js";function t(t,n,r){return e(t,e=>{throw Error(`Use per-request wrapper`)},r),async function(i,a){let o=`${i.headers[`x-forwarded-proto`]??`http`}://${i.headers.host}${i.url}`,s=i.method?.toUpperCase()||`GET`,c=new Request(o,{method:s,headers:Object.fromEntries(Object.entries(i.headers).map(([e,t])=>[e,String(t)])),body:s===`POST`?JSON.stringify(i.body??{}):void 0}),l=await e(t,()=>n(i),r)(c);a.status(l.status),l.headers.forEach((e,t)=>a.setHeader(t,e));let u=await l.text();a.send(u)}}export{t as makeNextPagesHandler};
+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

@@ -1 +1,48 @@
-var e=class{onAnomaly;now;samples=new Map;constructor(e={}){this.onAnomaly=e.onAnomaly,this.now=e.now??(()=>new Date)}observe(e){let t=e.definition.anomalyDetection;if(!t?.enabled||!t.thresholds?.length)return;let n=`${e.name}.v${e.version}`,r=(this.samples.get(n)??0)+1;if(this.samples.set(n,r),!(typeof t.minimumSample==`number`&&r<t.minimumSample))for(let n of t.thresholds){let r=this.extractMetric(e,n.metric);typeof r==`number`&&(typeof n.min==`number`&&r<n.min&&this.emit(e,t,n.metric,r,`min`),typeof n.max==`number`&&r>n.max&&this.emit(e,t,n.metric,r,`max`))}}extractMetric(e,t){let n=e.properties[t];if(typeof n==`number`)return n;if(typeof n==`object`&&n&&`value`in n){let e=n.value;return typeof e==`number`?e:void 0}}emit(e,t,n,r,i){this.onAnomaly?.({dispatch:e,threshold:t,metric:n,value:r,type:i})}reset(){this.samples.clear()}};export{e as TelemetryAnomalyMonitor};
+//#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 "@lssm/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

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

@@ -1 +1,5 @@
-import{TelemetryRegistry as e,makeTelemetryKey as t}from"./spec.js";import{TelemetryTracker as n}from"./tracker.js";import{TelemetryAnomalyMonitor as r}from"./anomaly.js";export{r as TelemetryAnomalyMonitor,e as TelemetryRegistry,n as TelemetryTracker,t as makeTelemetryKey};
+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";
+
+//#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: number;
+  /** 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 {
+  private readonly items;
+  private readonly eventsByKey;
+  private readonly specByEventKey;
+  register(spec: TelemetrySpec): this;
+  list(): TelemetrySpec[];
+  get(key: string, version?: number): TelemetrySpec | undefined;
+  findEventDef(name: string, version?: number): TelemetryEventDef | undefined;
+  getSpecForEvent(name: string, version?: number): 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

@@ -1 +1,69 @@
-const e=e=>`${e.name}.v${e.version}`;var t=class{items=new Map;eventsByKey=new Map;specByEventKey=new Map;register(t){let n=e(t.meta);if(this.items.has(n))throw Error(`Duplicate TelemetrySpec registration for ${n}`);this.items.set(n,t);for(let e of t.events)this.eventsByKey.set(`${e.name}.v${e.version}`,e),this.specByEventKey.set(`${e.name}.v${e.version}`,t);return this}list(){return[...this.items.values()]}get(e,t){if(t!=null)return this.items.get(`${e}.v${t}`);let n,r=-1/0;for(let t of this.items.values())t.meta.name===e&&t.meta.version>r&&(r=t.meta.version,n=t);return n}findEventDef(e,t){if(t!=null)return this.eventsByKey.get(`${e}.v${t}`);let n,r=-1/0;for(let[t,i]of this.eventsByKey.entries()){let[a,o]=t.split(`.v`);if(a!==e)continue;let s=Number(o);Number.isFinite(s)&&s>r&&(r=s,n=i)}return n}getSpecForEvent(e,t){if(t!=null)return this.specByEventKey.get(`${e}.v${t}`);let n,r=-1/0;for(let[t,i]of this.specByEventKey.entries()){let[a,o]=t.split(`.v`);if(a!==e)continue;let s=Number(o);Number.isFinite(s)&&s>r&&(r=s,n=i)}return n}};function n(t){return e(t)}export{t as TelemetryRegistry,n as makeTelemetryKey};
+//#region src/telemetry/spec.ts
+const telemetryKey = (meta) => `${meta.key}.v${meta.version}`;
+var TelemetryRegistry = class {
+	items = /* @__PURE__ */ new Map();
+	eventsByKey = /* @__PURE__ */ new Map();
+	specByEventKey = /* @__PURE__ */ new Map();
+	register(spec) {
+		const key = telemetryKey(spec.meta);
+		if (this.items.has(key)) throw new Error(`Duplicate TelemetrySpec registration for ${key}`);
+		this.items.set(key, 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);
+		}
+		return this;
+	}
+	list() {
+		return [...this.items.values()];
+	}
+	get(key, version) {
+		if (version != null) return this.items.get(`${key}.v${version}`);
+		let latest;
+		let maxVersion = -Infinity;
+		for (const item of this.items.values()) {
+			if (item.meta.key !== key) continue;
+			if (item.meta.version > maxVersion) {
+				maxVersion = item.meta.version;
+				latest = item;
+			}
+		}
+		return latest;
+	}
+	findEventDef(name, version) {
+		if (version != null) return this.eventsByKey.get(`${name}.v${version}`);
+		let latest;
+		let maxVersion = -Infinity;
+		for (const [key, event] of this.eventsByKey.entries()) {
+			const [eventName, versionPart] = key.split(".v");
+			if (eventName !== name) continue;
+			const ver = Number(versionPart);
+			if (Number.isFinite(ver) && ver > maxVersion) {
+				maxVersion = ver;
+				latest = event;
+			}
+		}
+		return latest;
+	}
+	getSpecForEvent(name, version) {
+		if (version != null) return this.specByEventKey.get(`${name}.v${version}`);
+		let latest;
+		let maxVersion = -Infinity;
+		for (const [key, spec] of this.specByEventKey.entries()) {
+			const [eventName, versionPart] = key.split(".v");
+			if (eventName !== name) continue;
+			const ver = Number(versionPart);
+			if (Number.isFinite(ver) && ver > maxVersion) {
+				maxVersion = ver;
+				latest = spec;
+			}
+		}
+		return latest;
+	}
+};
+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: number;
+  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: number, properties: Record<string, unknown>, context?: TelemetryEventContext): Promise<boolean>;
+  private shouldSample;
+  private redactProperties;
+}
+//#endregion
+export { RuntimeTelemetryProvider, TelemetryDispatch, TelemetryEventContext, TelemetryTracker, TelemetryTrackerOptions };

package/dist/telemetry/tracker.js

@@ -1 +1,76 @@
-import{randomUUID as e}from"crypto";const t=e=>e==null?e:typeof e==`string`?`REDACTED`:typeof e==`number`?0:typeof e==`boolean`?!1:Array.isArray(e)?e.map(()=>`REDACTED`):typeof e==`object`?Object.fromEntries(Object.keys(e).map(e=>[e,`REDACTED`])):`REDACTED`;var n=class{providers=new Map;registry;anomalyMonitor;random;clock;constructor(e){this.registry=e.registry,this.anomalyMonitor=e.anomalyMonitor,this.random=e.random??Math.random,this.clock=e.clock??(()=>new Date);for(let t of e.providers??[])this.providers.set(t.id,t)}registerProvider(e){this.providers.set(e.id,e)}unregisterProvider(e){this.providers.delete(e)}async track(t,n,r,i={}){let a=this.registry.findEventDef(t,n);if(!a)return!1;let o=this.registry.getSpecForEvent(a.name,a.version);if(!o||!this.shouldSample(a.sampling??o.config?.defaultSamplingRate))return!1;let s=this.redactProperties(a,r),c={id:e(),name:a.name,version:a.version,occurredAt:this.clock().toISOString(),properties:s,privacy:a.privacy,context:i,tags:a.tags,spec:o,definition:a};return await Promise.all([...this.providers.values()].map(e=>e.send(c))),this.anomalyMonitor?.observe(c),!0}shouldSample(e){return typeof e==`number`?this.random()<e:e?this.random()<e.rate:!0}redactProperties(e,n){let r={};for(let[i,a]of Object.entries(n)){let n=e.properties[i];if(!n){r[i]=a;continue}n.redact||n.pii||e.privacy===`sensitive`?r[i]=t(a):r[i]=a}return r}};export{n as TelemetryTracker};
+import { randomUUID } from "crypto";
+
+//#region src/telemetry/tracker.ts
+const maskValue = (value) => {
+	if (value == null) return value;
+	if (typeof value === "string") return "REDACTED";
+	if (typeof value === "number") return 0;
+	if (typeof value === "boolean") return false;
+	if (Array.isArray(value)) return value.map(() => "REDACTED");
+	if (typeof value === "object") return Object.fromEntries(Object.keys(value).map((key) => [key, "REDACTED"]));
+	return "REDACTED";
+};
+var TelemetryTracker = class {
+	providers = /* @__PURE__ */ new Map();
+	registry;
+	anomalyMonitor;
+	random;
+	clock;
+	constructor(options) {
+		this.registry = options.registry;
+		this.anomalyMonitor = options.anomalyMonitor;
+		this.random = options.random ?? Math.random;
+		this.clock = options.clock ?? (() => /* @__PURE__ */ new Date());
+		for (const provider of options.providers ?? []) this.providers.set(provider.id, provider);
+	}
+	registerProvider(provider) {
+		this.providers.set(provider.id, provider);
+	}
+	unregisterProvider(providerId) {
+		this.providers.delete(providerId);
+	}
+	async track(name, version, properties, context = {}) {
+		const definition = this.registry.findEventDef(name, version);
+		if (!definition) return false;
+		const spec = this.registry.getSpecForEvent(definition.key, definition.version);
+		if (!spec) return false;
+		if (!this.shouldSample(definition.sampling ?? spec.config?.defaultSamplingRate)) return false;
+		const redactedProperties = this.redactProperties(definition, properties);
+		const dispatch = {
+			id: randomUUID(),
+			name: definition.key,
+			version: definition.version,
+			occurredAt: this.clock().toISOString(),
+			properties: redactedProperties,
+			privacy: definition.privacy,
+			context,
+			tags: definition.tags,
+			spec,
+			definition
+		};
+		await Promise.all([...this.providers.values()].map((provider) => provider.send(dispatch)));
+		this.anomalyMonitor?.observe(dispatch);
+		return true;
+	}
+	shouldSample(sampling) {
+		if (typeof sampling === "number") return this.random() < sampling;
+		if (!sampling) return true;
+		return this.random() < sampling.rate;
+	}
+	redactProperties(definition, properties) {
+		const result = {};
+		for (const [key, value] of Object.entries(properties)) {
+			const def = definition.properties[key];
+			if (!def) {
+				result[key] = value;
+				continue;
+			}
+			if (def.redact || def.pii || definition.privacy === "sensitive") result[key] = maskValue(value);
+			else result[key] = value;
+		}
+		return result;
+	}
+};
+
+//#endregion
+export { TelemetryTracker };

package/dist/tests/index.d.ts

@@ -0,0 +1,3 @@
+import { Action, Assertion, CoverageRequirement, ExpectErrorAssertion, ExpectEventsAssertion, ExpectOutputAssertion, ExpectedEvent, Fixture, OperationTargetRef, TestRegistry, TestScenario, TestSpec, TestSpecMeta, TestSpecRef, TestTarget, WorkflowTargetRef, makeTestKey } from "./spec.js";
+import { AssertionResult, ScenarioRunResult, TestRunResult, TestRunner, TestRunnerConfig } from "./runner.js";
+export { Action, Assertion, AssertionResult, CoverageRequirement, ExpectErrorAssertion, ExpectEventsAssertion, ExpectOutputAssertion, ExpectedEvent, Fixture, OperationTargetRef, ScenarioRunResult, TestRegistry, TestRunResult, TestRunner, TestRunnerConfig, TestScenario, TestSpec, TestSpecMeta, TestSpecRef, TestTarget, WorkflowTargetRef, makeTestKey };

package/dist/tests/index.js

@@ -1 +1,4 @@
-import{TestRegistry as e,makeTestKey as t}from"./spec.js";import{TestRunner as n}from"./runner.js";export{e as TestRegistry,n as TestRunner,t as makeTestKey};
+import { TestRegistry, makeTestKey } from "./spec.js";
+import { TestRunner } from "./runner.js";
+
+export { TestRegistry, TestRunner, makeTestKey };