@lssm/lib.contracts 0.0.0-canary-20251217062943 → 0.0.0-canary-20251217072406

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.js

@@ -1,139 +1,22 @@
-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";
+import "../../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- `SpecRegistry.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.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.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.name}.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.name}.v${event.version}`, event);
+			this.specByEventKey.set(`${event.name}.v${event.version}`, spec);
+		}
+		return this;
+	}
+	list() {
+		return [...this.items.values()];
+	}
+	get(name, version) {
+		if (version != null) return this.items.get(`${name}.v${version}`);
+		let latest;
+		let maxVersion = -Infinity;
+		for (const item of this.items.values()) {
+			if (item.meta.name !== name) 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.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.name, 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.name,
+			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.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 };

package/dist/tests/runner.js

@@ -1 +1,150 @@
-import"../index.js";import{deepStrictEqual as e}from"node:assert";var t=class{constructor(e){this.config=e}async run(e){let t=[],n=0,r=0;for(let i of e.scenarios){await this.config.beforeEach?.(i);let a=await this.runScenario(e,i);t.push(a),a.status===`passed`?n+=1:r+=1,await this.config.afterEach?.(i,a)}return{spec:e,scenarios:t,passed:n,failed:r}}async runScenario(e,t){let n=[];try{let r=await this.createContext(),i=[...e.fixtures??[],...t.given??[]],a=[];for(let e of i)await this.executeOperation(e,r,a);let o=await this.executeOperation(t.when,r,a),s=t.then??[];for(let e of s){let t=this.evaluateAssertion(e,o,a);n.push(t)}return{scenario:t,status:n.some(e=>e.status===`failed`)?`failed`:`passed`,assertionResults:n}}catch(e){return{scenario:t,status:`failed`,error:e,assertionResults:n}}}async createContext(){return{...await this.config.createContext?.()??{}}}async executeOperation(e,t,n){let r={...t,eventPublisher:async e=>{n.push({name:e.name,version:e.version,payload:e.payload}),await t.eventPublisher?.(e)}};try{return{output:await this.config.registry.execute(e.operation.name,e.operation.version,e.input??null,r),events:n}}catch(e){return{error:e,events:n}}}evaluateAssertion(e,t,n){switch(e.type){case`expectOutput`:return this.evaluateOutputAssertion(e,t);case`expectError`:return this.evaluateErrorAssertion(e,t);case`expectEvents`:return this.evaluateEventsAssertion(e,n);default:return{assertion:e,status:`failed`,message:`Unknown assertion type ${e.type}`}}}evaluateOutputAssertion(t,n){if(n.error)return{assertion:t,status:`failed`,message:`Expected output but operation threw error: ${n.error.message}`};try{return e(n.output,t.match),{assertion:t,status:`passed`}}catch(e){return{assertion:t,status:`failed`,message:e instanceof Error?e.message:`Output assertion failed`}}}evaluateErrorAssertion(e,t){return t.error?e.messageIncludes&&!t.error.message.includes(e.messageIncludes)?{assertion:e,status:`failed`,message:`Error message "${t.error.message}" did not include expected substring "${e.messageIncludes}"`}:{assertion:e,status:`passed`}:{assertion:e,status:`failed`,message:`Expected an error but operation completed successfully`}}evaluateEventsAssertion(e,t){let n=[];for(let r of e.events){let e=t.filter(e=>e.name===r.name&&e.version===r.version).length;typeof r.min==`number`&&e<r.min||typeof r.max==`number`&&e>r.max?n.push(`Event ${r.name}.v${r.version} occurred ${e} times (expected ${r.min??0} - ${r.max??`∞`})`):r.min===void 0&&r.max===void 0&&e===0&&n.push(`Event ${r.name}.v${r.version} did not occur`)}return n.length>0?{assertion:e,status:`failed`,message:n.join(`; `)}:{assertion:e,status:`passed`}}};export{t as TestRunner};
+import "../index.js";
+import { deepStrictEqual } from "node:assert";
+
+//#region src/tests/runner.ts
+var TestRunner = class {
+	constructor(config) {
+		this.config = config;
+	}
+	async run(spec) {
+		const scenarios = [];
+		let passed = 0;
+		let failed = 0;
+		for (const scenario of spec.scenarios) {
+			await this.config.beforeEach?.(scenario);
+			const result = await this.runScenario(spec, scenario);
+			scenarios.push(result);
+			if (result.status === "passed") passed += 1;
+			else failed += 1;
+			await this.config.afterEach?.(scenario, result);
+		}
+		return {
+			spec,
+			scenarios,
+			passed,
+			failed
+		};
+	}
+	async runScenario(spec, scenario) {
+		const assertionResults = [];
+		try {
+			const context = await this.createContext();
+			const fixtures = [...spec.fixtures ?? [], ...scenario.given ?? []];
+			const events = [];
+			for (const fixture of fixtures) await this.executeOperation(fixture, context, events);
+			const actionResult = await this.executeOperation(scenario.when, context, events);
+			const assertions = scenario.then ?? [];
+			for (const assertion of assertions) {
+				const assertionResult = this.evaluateAssertion(assertion, actionResult, events);
+				assertionResults.push(assertionResult);
+			}
+			return {
+				scenario,
+				status: assertionResults.some((assertion) => assertion.status === "failed") ? "failed" : "passed",
+				assertionResults
+			};
+		} catch (error) {
+			return {
+				scenario,
+				status: "failed",
+				error,
+				assertionResults
+			};
+		}
+	}
+	async createContext() {
+		return { ...await this.config.createContext?.() ?? {} };
+	}
+	async executeOperation(action, baseCtx, recordedEvents) {
+		const ctx = {
+			...baseCtx,
+			eventPublisher: async (event) => {
+				recordedEvents.push({
+					name: event.name,
+					version: event.version,
+					payload: event.payload
+				});
+				await baseCtx.eventPublisher?.(event);
+			}
+		};
+		try {
+			return {
+				output: await this.config.registry.execute(action.operation.name, action.operation.version, action.input ?? null, ctx),
+				events: recordedEvents
+			};
+		} catch (error) {
+			return {
+				error,
+				events: recordedEvents
+			};
+		}
+	}
+	evaluateAssertion(assertion, result, events) {
+		switch (assertion.type) {
+			case "expectOutput": return this.evaluateOutputAssertion(assertion, result);
+			case "expectError": return this.evaluateErrorAssertion(assertion, result);
+			case "expectEvents": return this.evaluateEventsAssertion(assertion, events);
+			default: return {
+				assertion,
+				status: "failed",
+				message: `Unknown assertion type ${assertion.type}`
+			};
+		}
+	}
+	evaluateOutputAssertion(assertion, result) {
+		if (result.error) return {
+			assertion,
+			status: "failed",
+			message: `Expected output but operation threw error: ${result.error.message}`
+		};
+		try {
+			deepStrictEqual(result.output, assertion.match);
+			return {
+				assertion,
+				status: "passed"
+			};
+		} catch (error) {
+			return {
+				assertion,
+				status: "failed",
+				message: error instanceof Error ? error.message : "Output assertion failed"
+			};
+		}
+	}
+	evaluateErrorAssertion(assertion, result) {
+		if (!result.error) return {
+			assertion,
+			status: "failed",
+			message: "Expected an error but operation completed successfully"
+		};
+		if (assertion.messageIncludes && !result.error.message.includes(assertion.messageIncludes)) return {
+			assertion,
+			status: "failed",
+			message: `Error message "${result.error.message}" did not include expected substring "${assertion.messageIncludes}"`
+		};
+		return {
+			assertion,
+			status: "passed"
+		};
+	}
+	evaluateEventsAssertion(assertion, events) {
+		const failures = [];
+		for (const expected of assertion.events) {
+			const count = events.filter((event) => event.name === expected.name && event.version === expected.version).length;
+			if (typeof expected.min === "number" && count < expected.min || typeof expected.max === "number" && count > expected.max) failures.push(`Event ${expected.name}.v${expected.version} occurred ${count} times (expected ${expected.min ?? 0} - ${expected.max ?? "∞"})`);
+			else if (typeof expected.min === "undefined" && typeof expected.max === "undefined" && count === 0) failures.push(`Event ${expected.name}.v${expected.version} did not occur`);
+		}
+		if (failures.length > 0) return {
+			assertion,
+			status: "failed",
+			message: failures.join("; ")
+		};
+		return {
+			assertion,
+			status: "passed"
+		};
+	}
+};
+
+//#endregion
+export { TestRunner };

package/dist/tests/spec.js

@@ -1 +1,33 @@
-const e=e=>`${e.name}.v${e.version}`;var t=class{items=new Map;register(t){let n=e(t.meta);if(this.items.has(n))throw Error(`Duplicate TestSpec registration for ${n}`);return this.items.set(n,t),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}};function n(t){return e(t)}export{t as TestRegistry,n as makeTestKey};
+//#region src/tests/spec.ts
+const testKey = (meta) => `${meta.name}.v${meta.version}`;
+var TestRegistry = class {
+	items = /* @__PURE__ */ new Map();
+	register(spec) {
+		const key = testKey(spec.meta);
+		if (this.items.has(key)) throw new Error(`Duplicate TestSpec registration for ${key}`);
+		this.items.set(key, spec);
+		return this;
+	}
+	list() {
+		return [...this.items.values()];
+	}
+	get(name, version) {
+		if (version != null) return this.items.get(`${name}.v${version}`);
+		let latest;
+		let maxVersion = -Infinity;
+		for (const spec of this.items.values()) {
+			if (spec.meta.name !== name) continue;
+			if (spec.meta.version > maxVersion) {
+				maxVersion = spec.meta.version;
+				latest = spec;
+			}
+		}
+		return latest;
+	}
+};
+function makeTestKey(meta) {
+	return testKey(meta);
+}
+
+//#endregion
+export { TestRegistry, makeTestKey };

package/dist/themes.js

@@ -1 +1,39 @@
-const e=e=>`${e.name}.v${e.version}`;var t=class{items=new Map;register(t){let n=e(t.meta);if(this.items.has(n))throw Error(`Duplicate theme ${n}`);return this.items.set(n,t),this}list(){return[...this.items.values()]}get(t,n){if(n!=null)return this.items.get(e({name:t,version:n}));let r,i=-1/0;for(let e of this.items.values())e.meta.name===t&&e.meta.version>i&&(i=e.meta.version,r=e);return r}};function n(e){return{name:e.meta.name,version:e.meta.version}}export{t as ThemeRegistry,n as makeThemeRef};
+//#region src/themes.ts
+const themeKey = (ref) => `${ref.name}.v${ref.version}`;
+var ThemeRegistry = class {
+	items = /* @__PURE__ */ new Map();
+	register(spec) {
+		const key = themeKey(spec.meta);
+		if (this.items.has(key)) throw new Error(`Duplicate theme ${key}`);
+		this.items.set(key, spec);
+		return this;
+	}
+	list() {
+		return [...this.items.values()];
+	}
+	get(name, version) {
+		if (version != null) return this.items.get(themeKey({
+			name,
+			version
+		}));
+		let candidate;
+		let max = -Infinity;
+		for (const spec of this.items.values()) {
+			if (spec.meta.name !== name) continue;
+			if (spec.meta.version > max) {
+				max = spec.meta.version;
+				candidate = spec;
+			}
+		}
+		return candidate;
+	}
+};
+function makeThemeRef(spec) {
+	return {
+		name: spec.meta.name,
+		version: spec.meta.version
+	};
+}
+
+//#endregion
+export { ThemeRegistry, makeThemeRef };