@contractspec/lib.contracts 1.44.0

package/dist/docs/tech/vscode-extension.docblock.d.ts

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

package/dist/docs/tech/vscode-extension.docblock.js

@@ -0,0 +1,102 @@
+import { registerDocBlocks } from "../registry.js";
+
+//#region src/docs/tech/vscode-extension.docblock.ts
+const tech_vscode_extension_DocBlocks = [{
+	id: "docs.tech.vscode.extension",
+	title: "ContractSpec VS Code Extension",
+	summary: "VS Code extension for spec-first development with validation, scaffolding, and MCP integration.",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/vscode/extension",
+	tags: [
+		"vscode",
+		"extension",
+		"tooling",
+		"dx"
+	],
+	body: `# ContractSpec VS Code Extension
+
+The ContractSpec VS Code extension provides spec-first development tooling directly in your editor.
+
+## Features
+
+- **Real-time Validation**: Get instant feedback on spec errors and warnings as you save files
+- **Build/Scaffold**: Generate handler and component skeletons from specs (no AI required)
+- **Spec Explorer**: List and navigate all specs in your workspace
+- **Dependency Analysis**: Visualize spec dependencies and detect cycles
+- **MCP Integration**: Search ContractSpec documentation via Model Context Protocol
+- **Snippets**: Code snippets for common ContractSpec patterns
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| \`ContractSpec: Validate Current Spec\` | Validate the currently open spec file |
+| \`ContractSpec: Validate All Specs\` | Validate all spec files in the workspace |
+| \`ContractSpec: Build/Scaffold\` | Generate handler/component from the current spec |
+| \`ContractSpec: List All Specs\` | Show all specs in the workspace |
+| \`ContractSpec: Analyze Dependencies\` | Analyze and visualize spec dependencies |
+| \`ContractSpec: Search Docs (MCP)\` | Search documentation via MCP |
+
+## Configuration
+
+| Setting | Description | Default |
+|---------|-------------|---------|
+| \`contractspec.api.baseUrl\` | Base URL for ContractSpec API (enables MCP + remote telemetry) | \`""\` |
+| \`contractspec.telemetry.posthogHost\` | PostHog host URL for direct telemetry | \`"https://eu.posthog.com"\` |
+| \`contractspec.telemetry.posthogProjectKey\` | PostHog project key for direct telemetry | \`""\` |
+| \`contractspec.validation.onSave\` | Run validation on save | \`true\` |
+| \`contractspec.validation.onOpen\` | Run validation on open | \`true\` |
+
+## Architecture
+
+The extension uses:
+- \`@contractspec/module.workspace\` for pure analysis + templates
+- \`@contractspec/bundle.workspace\` for workspace services + adapters
+
+This allows the extension to work without requiring the CLI to be installed.
+
+## Telemetry
+
+The extension uses a hybrid telemetry approach:
+1. If \`contractspec.api.baseUrl\` is configured → send to API \`/api/telemetry/ingest\`
+2. Otherwise → send directly to PostHog (if project key configured)
+
+Telemetry respects VS Code's telemetry settings. No file paths, source code, or PII is collected.
+`
+}, {
+	id: "docs.tech.vscode.snippets",
+	title: "ContractSpec Snippets",
+	summary: "Code snippets for common ContractSpec patterns in VS Code.",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/vscode/snippets",
+	tags: [
+		"vscode",
+		"snippets",
+		"dx"
+	],
+	body: `# ContractSpec Snippets
+
+The VS Code extension includes snippets for common ContractSpec patterns.
+
+## Available Snippets
+
+| Prefix | Description |
+|--------|-------------|
+| \`contractspec-command\` | Create a new command (write operation) |
+| \`contractspec-query\` | Create a new query (read-only operation) |
+| \`contractspec-event\` | Create a new event |
+| \`contractspec-docblock\` | Create a new DocBlock |
+| \`contractspec-telemetry\` | Create a new TelemetrySpec |
+| \`contractspec-presentation\` | Create a new Presentation |
+
+## Usage
+
+Type the prefix in a TypeScript file and press Tab to expand the snippet. Tab through the placeholders to fill in your values.
+`
+}];
+registerDocBlocks(tech_vscode_extension_DocBlocks);
+
+//#endregion
+export { tech_vscode_extension_DocBlocks };

package/dist/docs/tech-contracts.docs.d.ts

@@ -0,0 +1,6 @@
+import { DocBlock } from "./types.js";
+
+//#region src/docs/tech-contracts.docs.d.ts
+declare const techContractsDocs: DocBlock[];
+//#endregion
+export { techContractsDocs };

package/dist/docs/tech-contracts.docs.js

@@ -0,0 +1,96 @@
+import { registerDocBlocks } from "./registry.js";
+
+//#region src/docs/tech-contracts.docs.ts
+const techContractsDocs = [{
+	id: "docs.tech.contracts.presentations-v2",
+	title: "Presentations V2 — Unified Descriptor & Transform Engine",
+	summary: "How PresentationSpec and TransformEngine keep docs/renderers consistent.",
+	visibility: "public",
+	route: "/docs/tech/contracts/presentations-v2",
+	kind: "reference",
+	tags: [
+		"presentations",
+		"docs",
+		"mcp"
+	],
+	body: `## Presentations V2 — Unified Descriptor & Transform Engine
+
+### Purpose
+
+Unify presentations into one descriptor (\`PresentationSpec\`) that declares a single source (React component key or BlockNote doc) and a list of output targets (react, markdown, application/json, application/xml). A pluggable \`TransformEngine\` renders any target and applies PII redaction.
+
+### Types
+
+\`\`\`ts
+type PresentationTarget =
+  | 'react'
+  | 'markdown'
+  | 'application/json'
+  | 'application/xml';
+
+type PresentationSource =
+  | {
+      type: 'component';
+      framework: 'react';
+      componentKey: string;
+      props?: AnySchemaModel;
+    }
+  | { type: 'blocknotejs'; docJson: unknown; blockConfig?: unknown };
+
+interface PresentationSpec {
+  meta: PresentationMeta; // includes partial OwnerShipMeta + description
+  policy?: { flags?: string[]; pii?: string[] };
+  source: PresentationSource;
+  targets: PresentationTarget[];
+}
+
+// Shared ownership schema (source of truth in @contractspec/lib.contracts/src/ownership.ts)
+interface OwnerShipMeta {
+  title: string;
+  description: string;
+  domain: string;
+  owners: Owner[];
+  tags: Tag[];
+  stability: Stability;
+}
+
+type Stability = 'experimental' | 'beta' | 'stable' | 'deprecated';
+type Owner = string; // curated list available in code (e.g., '@sigil-team', 'team-strit')
+type Tag = string; // curated list available in code (e.g., 'auth', 'spots')
+
+// For presentations, meta is a Partial<OwnerShipMeta> plus description, name, version
+interface PresentationMeta extends Partial<OwnerShipMeta> {
+  name: string;
+  version: number;
+  description?: string;
+}
+\`\`\`
+
+### Engine
+
+Use \`createDefaultTransformEngine()\` and register custom renderers as needed (e.g., high-fidelity BlockNote → Markdown). The default engine supports markdown/json/xml; a React renderer returns a serializable descriptor the host app renders via a \`componentMap\` or a BlockNote renderer. The canonical source type string is \`blocknotejs\` (not \`blocknote\`).
+
+PII paths (JSON-like) are redacted from rendered outputs.
+
+### MCP Integration
+
+\`createMcpServer\` accepts \`presentationsV2\`. Each descriptor is exposed under \`presentation://<name>/v<version>\` and negotiated variants (\`.md/.json/.xml\`) are rendered by the engine.
+
+### Migration
+
+- V1 \`PresentationSpec\` remains supported; a back-compat helper converts V1 → V2 when convenient.
+- Prefer V2 for new work.
+
+### Examples (Sigil)
+
+- \`sigil.auth.webauth_tabs_v2\`: component source (\`componentKey: 'sigil.webauth.tabs'\`), targets \`react/json/xml\`.
+- \`sigil.signup.guide_v2\`: BlockNote doc source, targets \`react/markdown/json/xml\`.
+
+### React Rendering
+
+Host apps use a \`componentMap\` (e.g., \`'sigil.webauth.tabs' → WebAuthTabs\`) and a BlockNote renderer to turn the React render descriptor into elements.`
+}];
+registerDocBlocks(techContractsDocs);
+
+//#endregion
+export { techContractsDocs };

package/dist/docs/types.d.ts

@@ -0,0 +1,41 @@
+import { Stability } from "../ownership.js";
+
+//#region src/docs/types.d.ts
+type DocVisibility = 'public' | 'internal' | 'mixed';
+interface DocBlockLink {
+  label: string;
+  href: string;
+}
+type DocKind = 'goal' | 'how' | 'usage' | 'reference' | 'faq';
+interface DocBlock {
+  /** Globally unique identifier (prefer dotted paths like docs.ops.runbook). */
+  id: string;
+  /** Short, human-readable title. */
+  title: string;
+  /** Markdown body (LLM- and human-readable). */
+  body: string;
+  /** Optional one-line summary used for meta.description. */
+  summary?: string;
+  /** Explicit route (e.g., /docs/ops/anomaly-detection). Falls back to id-derived route. */
+  route?: string;
+  /** Optional semantic grouping for filtering. */
+  kind?: DocKind;
+  /** Visibility gate. Defaults to public. */
+  visibility?: DocVisibility;
+  /** Optional version to allow evolutions without breaking links. Defaults to 1. */
+  version?: number;
+  /** Tags to aid discovery and filtering. */
+  tags?: string[];
+  /** Owning teams or individuals. */
+  owners?: string[];
+  /** Related contract/presentation identifiers. */
+  relatedSpecs?: string[];
+  /** External references or supporting links. */
+  links?: DocBlockLink[];
+  /** Domain or bounded context marker. */
+  domain?: string;
+  /** Stability marker to mirror presentation ownership semantics. */
+  stability?: Stability;
+}
+//#endregion
+export { DocBlock, DocBlockLink, DocKind, DocVisibility };

package/dist/events.d.ts

@@ -0,0 +1,47 @@
+import { DocId } from "./docs/registry.js";
+import { OwnerShipMeta } from "./ownership.js";
+import { SpecContractRegistry } from "./registry.js";
+import { AnySchemaModel } from "@contractspec/lib.schema";
+
+//#region src/events.d.ts
+interface EventSpecMeta extends Omit<OwnerShipMeta, 'docId'> {
+  /** Doc block(s) for this operation. */
+  docId?: DocId[];
+}
+/**
+ * Typed event specification. Declare once, validate payloads at publish time,
+ * and guard emissions via the contracts runtime.
+ */
+interface EventSpec<T extends AnySchemaModel> {
+  meta: EventSpecMeta;
+  /** JSON-like paths to redact from logs/exports. */
+  pii?: string[];
+  /** Event payload schema from @contractspec/lib.schema. */
+  payload: T;
+}
+type AnyEventSpec<T extends AnySchemaModel = AnySchemaModel> = EventSpec<T>;
+/** Identity function to keep type inference when declaring events. */
+declare function defineEvent<T extends AnySchemaModel>(e: EventSpec<T>): EventSpec<T>;
+interface EventEnvelope<T> {
+  /** Unique identifier for the published event (UUID recommended). */
+  id: string;
+  /** ISO timestamp when the event occurred. */
+  occurredAt: string;
+  /** Optional trace identifier for correlating across services. */
+  traceId?: string;
+  /** Event name as published (should match spec.name). */
+  key: string;
+  /** Event version as published (should match spec.version). */
+  version: number;
+  /** Validated payload. */
+  payload: T;
+}
+type EventKey = `${string}.v${number}`;
+/** Build a stable string key for an event name/version pair. */
+declare const eventKey: (key: string, version: number) => EventKey;
+/** In-memory registry for EventSpec. */
+declare class EventRegistry extends SpecContractRegistry<'event', AnyEventSpec> {
+  constructor(items?: AnyEventSpec[]);
+}
+//#endregion
+export { AnyEventSpec, EventEnvelope, EventKey, EventRegistry, EventSpec, EventSpecMeta, defineEvent, eventKey };

package/dist/events.js

@@ -0,0 +1,19 @@
+import { SpecContractRegistry } from "./registry.js";
+import "@contractspec/lib.schema";
+
+//#region src/events.ts
+/** Identity function to keep type inference when declaring events. */
+function defineEvent(e) {
+	return e;
+}
+/** Build a stable string key for an event name/version pair. */
+const eventKey = (key, version) => `${key}.v${version}`;
+/** In-memory registry for EventSpec. */
+var EventRegistry = class extends SpecContractRegistry {
+	constructor(items) {
+		super("event", items);
+	}
+};
+
+//#endregion
+export { EventRegistry, defineEvent, eventKey };

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

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

package/dist/experiments/docs/experiments.docblock.js

@@ -0,0 +1,21 @@
+import { registerDocBlocks } from "../../docs/registry.js";
+
+//#region src/experiments/docs/experiments.docblock.ts
+const tech_contracts_experiments_DocBlocks = [{
+	id: "docs.tech.contracts.experiments",
+	title: "ExperimentSpec & ExperimentEvaluator",
+	summary: "Use experiments to test alternative workflows, data views, or themes with controlled allocations and measurable outcomes.",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/contracts/experiments",
+	tags: [
+		"tech",
+		"contracts",
+		"experiments"
+	],
+	body: "# ExperimentSpec & ExperimentEvaluator\n\nUse experiments to test alternative workflows, data views, or themes with controlled allocations and measurable outcomes.\n\n- Types & registry: `packages/libs/contracts/src/experiments/spec.ts`\n- Runtime evaluator: `packages/libs/contracts/src/experiments/evaluator.ts`\n- CLI wizard/template: `contractspec create experiment`\n\n## Structure\n\n```ts\nexport interface ExperimentSpec {\n  meta: ExperimentMeta;\n  controlVariant: string;\n  variants: ExperimentVariant[];\n  allocation: AllocationStrategy;\n  successMetrics?: SuccessMetric[];\n}\n```\n\n- `variants`: define UI/behavior overrides (data views, workflows, themes, policies)\n- `allocation`:\n  - `random`: 50/50 or weighted via `weight`\n  - `sticky`: deterministic hash on user/organization/session\n  - `targeted`: rule-based (policy + expression + optional percentage)\n- `successMetrics`: telemetry events + aggregation (count/avg/p95) to track outcomes\n\n### Example\n\n```ts\nexport const OnboardingSplitFormExperiment: ExperimentSpec = {\n  meta: {\n    name: 'sigil.onboarding.split_form',\n    version: 1,\n    title: 'Split onboarding form',\n    description: 'Compare single vs multi-step onboarding',\n    domain: 'onboarding',\n    owners: ['@team.onboarding'],\n    tags: ['experiment'],\n    stability: StabilityEnum.Experimental,\n  },\n  controlVariant: 'control',\n  variants: [\n    { id: 'control', name: 'Single-step form' },\n    {\n      id: 'multi_step',\n      name: 'Multi-step form',\n      overrides: [\n        { type: 'workflow', target: 'sigil.onboarding.workflow.multi_step' },\n      ],\n    },\n  ],\n  allocation: {\n    type: 'targeted',\n    rules: [\n      {\n        variantId: 'multi_step',\n        expression: \"context.attributes?.segment === 'vip'\",\n      },\n    ],\n    fallback: 'random',\n  },\n  successMetrics: [\n    {\n      name: 'Completion rate',\n      telemetryEvent: { name: 'sigil.telemetry.onboarding_completed', version: 1 },\n      aggregation: 'count',\n    },\n  ],\n};\n```\n\n## Variant evaluation\n\n```ts\nconst evaluator = new ExperimentEvaluator({\n  registry: experimentRegistry,\n  policyChecker: (policyRef, context) =>\n    policyEngine.decide({\n      action: 'experiment_targeting',\n      subject: { roles: context.flags },\n      resource: { type: 'experiment', attributes: { name: context.experiment } },\n      policies: [policyRef],\n    }).effect === 'allow',\n});\n\nconst assignment = await evaluator.chooseVariant({\n  experiment: 'sigil.onboarding.split_form',\n  userId: ctx.userId,\n  organizationId: ctx.organizationId,\n  attributes: ctx.attributes,\n});\n\nif (assignment) {\n  // Apply overrides for the chosen variant\n  applyExperimentOverrides(assignment.variant);\n}\n```\n\n- `random` uses deterministic hashing (`salt` optional) for stable splits\n- `sticky` hashes a specified attribute (userId/orgId/sessionId)\n- `targeted` evaluates rules in order; each rule can reference a PolicySpec and simple JS expressions (`context` input)\n\n## Integrations\n\n- **Feature modules**: `FeatureModuleSpec.experiments` references experiments owned by a module\n- **DataViewSpec / WorkflowSpec**: `experiments?: ExperimentRef[]` indicate which experiments modify the spec\n- **Telemetry**: success metrics reference `TelemetrySpec` events to ensure compliant tracking\n- **Policy**: targeting rules call into `PolicyEngine` via the evaluator callback to respect privacy/security\n\n## CLI workflow\n\n```\ncontractspec create experiment\n```\n\n- Prompts for control/variants, allocation strategy, targeting rules, success metrics\n- Outputs a typed `ExperimentSpec` file alongside your contracts\n\n## Best practices\n\n1. Keep experiments short-lived; increment `meta.version` when changing allocation or variants.\n2. Always declare a control variant and ensure overrides are reversible.\n3. Tie success metrics to privacy-reviewed telemetry events.\n4. Use targeting rules sparingly; combine with PolicySpec to avoid exposing experiments to unauthorized users.\n5. When an experiment wins, promote the variant to the canonical spec and retire the experiment.\n\n"
+}];
+registerDocBlocks(tech_contracts_experiments_DocBlocks);
+
+//#endregion
+export { tech_contracts_experiments_DocBlocks };

package/dist/experiments/evaluator.d.ts

@@ -0,0 +1,37 @@
+import { PolicyRef } from "../policy/spec.js";
+import { ExperimentRegistry, ExperimentVariant } from "./spec.js";
+
+//#region src/experiments/evaluator.d.ts
+interface ExperimentContext {
+  experiment: string;
+  version?: number;
+  userId?: string | null;
+  organizationId?: string | null;
+  sessionId?: string | null;
+  attributes?: Record<string, unknown>;
+  flags?: string[];
+}
+interface ExperimentEvaluation {
+  variant: ExperimentVariant;
+  reason: 'control' | 'random' | 'sticky' | 'targeted';
+}
+interface ExperimentEvaluatorConfig {
+  registry: ExperimentRegistry;
+  policyChecker?: (policy: PolicyRef, context: ExperimentContext) => Promise<boolean> | boolean;
+  expressionEvaluator?: (expression: string, context: ExperimentContext) => boolean;
+}
+declare class ExperimentEvaluator {
+  private readonly registry;
+  private readonly policyChecker?;
+  private readonly expressionEvaluator?;
+  constructor(config: ExperimentEvaluatorConfig);
+  chooseVariant(context: ExperimentContext): Promise<ExperimentEvaluation | null>;
+  private pickByWeight;
+  private randomSeed;
+  private stickySeed;
+  private hashToUnitInterval;
+  private evaluateTargeting;
+  private matchesRule;
+}
+//#endregion
+export { ExperimentContext, ExperimentEvaluation, ExperimentEvaluator, ExperimentEvaluatorConfig };

package/dist/experiments/evaluator.js

@@ -0,0 +1,101 @@
+import { createHash } from "node:crypto";
+
+//#region src/experiments/evaluator.ts
+var ExperimentEvaluator = class {
+	registry;
+	policyChecker;
+	expressionEvaluator;
+	constructor(config) {
+		this.registry = config.registry;
+		this.policyChecker = config.policyChecker;
+		this.expressionEvaluator = config.expressionEvaluator;
+	}
+	async chooseVariant(context) {
+		const experiment = this.registry.get(context.experiment, context.version);
+		if (!experiment) return null;
+		const control = experiment.variants.find((variant) => variant.id === experiment.controlVariant);
+		if (!control) throw new Error(`Experiment ${experiment.meta.key} missing control variant ${experiment.controlVariant}`);
+		switch (experiment.allocation.type) {
+			case "random": return {
+				variant: this.pickByWeight(experiment, this.randomSeed(context, experiment.allocation.salt)),
+				reason: "random"
+			};
+			case "sticky": return {
+				variant: this.pickByWeight(experiment, this.stickySeed(context, experiment.allocation.attribute, experiment.allocation.salt)),
+				reason: "sticky"
+			};
+			case "targeted": {
+				const targeted = await this.evaluateTargeting(experiment, context, experiment.allocation.rules);
+				if (targeted) return {
+					variant: targeted,
+					reason: "targeted"
+				};
+				if (experiment.allocation.fallback === "random") return {
+					variant: this.pickByWeight(experiment, this.randomSeed(context)),
+					reason: "random"
+				};
+				return {
+					variant: control,
+					reason: "control"
+				};
+			}
+			default: return {
+				variant: control,
+				reason: "control"
+			};
+		}
+	}
+	pickByWeight(experiment, seed) {
+		const variants = experiment.variants;
+		const target = seed * variants.reduce((sum, variant) => sum + (variant.weight ?? 1), 0);
+		let cumulative = 0;
+		for (const variant of variants) {
+			cumulative += variant.weight ?? 1;
+			if (target <= cumulative) return variant;
+		}
+		return variants[variants.length - 1];
+	}
+	randomSeed(context, salt = "") {
+		const base = context.sessionId ?? context.userId ?? context.organizationId ?? `${Date.now()}-${Math.random()}`;
+		return this.hashToUnitInterval(base + salt);
+	}
+	stickySeed(context, attribute, salt = "") {
+		const value = context[attribute];
+		if (!value) return this.randomSeed(context, salt);
+		return this.hashToUnitInterval(`${value}-${salt}`);
+	}
+	hashToUnitInterval(value) {
+		const hash = createHash("sha256").update(value).digest("hex").slice(0, 15);
+		return parseInt(hash, 16) % 1e6 / 1e6;
+	}
+	async evaluateTargeting(experiment, context, rules) {
+		for (const rule of rules) {
+			if (!await this.matchesRule(rule, context)) continue;
+			const variant = experiment.variants.find((v) => v.id === rule.variantId);
+			if (!variant) continue;
+			if (typeof rule.percentage === "number") {
+				if (this.randomSeed(context, `rule-${rule.variantId}`) > rule.percentage) continue;
+			}
+			return variant;
+		}
+		return null;
+	}
+	async matchesRule(rule, context) {
+		if (rule.policy && this.policyChecker) {
+			if (!await this.policyChecker(rule.policy, context)) return false;
+		}
+		if (rule.expression) {
+			if (this.expressionEvaluator) return Boolean(this.expressionEvaluator(rule.expression, context));
+			try {
+				const fn = new Function("context", `return (${rule.expression});`);
+				return Boolean(fn(context));
+			} catch (_error) {
+				return false;
+			}
+		}
+		return true;
+	}
+};
+
+//#endregion
+export { ExperimentEvaluator };

package/dist/experiments/spec-resolver.d.ts

@@ -0,0 +1,17 @@
+import { ResourceRefDescriptor } from "../resources.js";
+import { HandlerCtx } from "../types.js";
+import { OpKind, OperationSpec } from "../operations/operation.js";
+import "../operations/index.js";
+import { AnySchemaModel } from "@contractspec/lib.schema";
+
+//#region src/experiments/spec-resolver.d.ts
+type RuntimeContract = OperationSpec<AnySchemaModel, AnySchemaModel | ResourceRefDescriptor<boolean>>;
+interface SpecVariantResolver {
+  resolve(operation: {
+    name: string;
+    version: number;
+    kind: OpKind;
+  }, ctx: HandlerCtx): Promise<RuntimeContract | undefined> | RuntimeContract | undefined;
+}
+//#endregion
+export { RuntimeContract, SpecVariantResolver };

package/dist/experiments/spec.d.ts

@@ -0,0 +1,82 @@
+import { OwnerShipMeta } from "../ownership.js";
+import { PolicyRef } from "../policy/spec.js";
+import { TelemetryEventDef } from "../telemetry/spec.js";
+
+//#region src/experiments/spec.d.ts
+type ExperimentMeta = OwnerShipMeta;
+interface ExperimentRef {
+  key: string;
+  version?: number;
+}
+type ExperimentOverrideType = 'dataView' | 'workflow' | 'theme' | 'policy' | 'presentation';
+interface ExperimentOverride {
+  type: ExperimentOverrideType;
+  /** Target spec meta name (e.g., DataViewspec.meta.key). */
+  target: string;
+  /** Target version. Optional; evaluator may choose latest when omitted. */
+  version?: number;
+  /** Optional configuration applied when this variant is active. */
+  config?: Record<string, unknown>;
+}
+interface ExperimentVariant {
+  id: string;
+  key: string;
+  description?: string;
+  /** Relative weight for random allocation (defaults to 1). */
+  weight?: number;
+  overrides?: ExperimentOverride[];
+  /** Optional metadata for downstream analytics/UI. */
+  metadata?: Record<string, unknown>;
+}
+interface TargetingRule {
+  /** Variant to assign when rule matches. */
+  variantId: string;
+  /** Optional percentage of matching traffic (0-1). If omitted, 100%. */
+  percentage?: number;
+  /** Policies that must allow the assignment. */
+  policy?: PolicyRef;
+  /** Expression evaluated against context (see evaluator for details). */
+  expression?: string;
+}
+type AllocationStrategy = {
+  type: 'random';
+  /** Optional salt for deterministic hashing. */
+  salt?: string;
+} | {
+  type: 'sticky';
+  /** Which attribute to hash for sticky assignment. */
+  attribute: 'userId' | 'organizationId' | 'sessionId';
+  salt?: string;
+} | {
+  type: 'targeted';
+  rules: TargetingRule[];
+  fallback?: 'control' | 'random';
+};
+type MetricAggregation = 'count' | 'avg' | 'p75' | 'p90' | 'p95' | 'p99';
+interface SuccessMetric {
+  key: string;
+  telemetryEvent: {
+    key: TelemetryEventDef['key'];
+    version: number;
+  };
+  aggregation: MetricAggregation;
+  target?: number;
+}
+interface ExperimentSpec {
+  meta: ExperimentMeta;
+  /** Identifier of the control variant (must exist in variants array). */
+  controlVariant: string;
+  variants: ExperimentVariant[];
+  allocation: AllocationStrategy;
+  successMetrics?: SuccessMetric[];
+  tags?: string[];
+}
+declare class ExperimentRegistry {
+  private readonly items;
+  register(spec: ExperimentSpec): this;
+  list(): ExperimentSpec[];
+  get(name: string, version?: number): ExperimentSpec | undefined;
+}
+declare function makeExperimentKey(meta: ExperimentMeta): string;
+//#endregion
+export { AllocationStrategy, ExperimentMeta, ExperimentOverride, ExperimentOverrideType, ExperimentRef, ExperimentRegistry, ExperimentSpec, ExperimentVariant, MetricAggregation, SuccessMetric, TargetingRule, makeExperimentKey };

package/dist/experiments/spec.js

@@ -0,0 +1,33 @@
+//#region src/experiments/spec.ts
+const experimentKey = (meta) => `${meta.key}.v${meta.version}`;
+var ExperimentRegistry = class {
+	items = /* @__PURE__ */ new Map();
+	register(spec) {
+		const key = experimentKey(spec.meta);
+		if (this.items.has(key)) throw new Error(`Duplicate experiment ${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.key !== name) continue;
+			if (spec.meta.version > maxVersion) {
+				maxVersion = spec.meta.version;
+				latest = spec;
+			}
+		}
+		return latest;
+	}
+};
+function makeExperimentKey(meta) {
+	return experimentKey(meta);
+}
+
+//#endregion
+export { ExperimentRegistry, makeExperimentKey };

package/dist/features/index.d.ts

@@ -0,0 +1,5 @@
+import { EventRef, FeatureModuleMeta, FeatureModuleSpec, FeatureRef, OpRef, PresentationRef } from "./types.js";
+import { FeatureRegistry } from "./registry.js";
+import { InstallFeatureDeps, installFeature } from "./install.js";
+import { validateFeatureTargetsV2 } from "./validation.js";
+export { type EventRef, type FeatureModuleMeta, type FeatureModuleSpec, type FeatureRef, FeatureRegistry, type InstallFeatureDeps, type OpRef, type PresentationRef, installFeature, validateFeatureTargetsV2 };

package/dist/features/index.js

@@ -0,0 +1,5 @@
+import { FeatureRegistry } from "./registry.js";
+import { installFeature } from "./install.js";
+import { validateFeatureTargetsV2 } from "./validation.js";
+
+export { FeatureRegistry, installFeature, validateFeatureTargetsV2 };