@contractspec/lib.contracts 0.0.0-canary-20260113162409

package/dist/examples/types.d.ts

@@ -0,0 +1,167 @@
+import { OwnerShipMeta } from "../ownership.js";
+import { FeatureModuleSpec, FeatureRef } from "../features/types.js";
+import "../features/index.js";
+import { AppBlueprintSpec, SpecPointer } from "../app-config/spec.js";
+
+//#region src/examples/types.d.ts
+/** Kind of example - determines how it's presented in catalogs */
+type ExampleKind = 'template' | 'workflow' | 'integration' | 'knowledge' | 'blueprint' | 'ui' | 'script' | 'library';
+declare const ExampleKindEnum: {
+  readonly Template: "template";
+  readonly Workflow: "workflow";
+  readonly Integration: "integration";
+  readonly Knowledge: "knowledge";
+  readonly Blueprint: "blueprint";
+  readonly UI: "ui";
+  readonly Script: "script";
+  readonly Library: "library";
+};
+/** Visibility level for examples */
+type ExampleVisibility = 'public' | 'internal' | 'experimental';
+declare const ExampleVisibilityEnum: {
+  readonly Public: "public";
+  readonly Internal: "internal";
+  readonly Experimental: "experimental";
+};
+/** Sandbox modes supported by examples */
+type ExampleSandboxMode = 'playground' | 'specs' | 'builder' | 'markdown' | 'evolution';
+declare const ExampleSandboxModeEnum: {
+  readonly Playground: "playground";
+  readonly Specs: "specs";
+  readonly Builder: "builder";
+  readonly Markdown: "markdown";
+  readonly Evolution: "evolution";
+};
+/** Documentation references for the example */
+interface ExampleDocumentation {
+  /** Root documentation block ID */
+  rootDocId?: string;
+  /** Goal/purpose documentation */
+  goalDocId?: string;
+  /** Usage/quickstart documentation */
+  usageDocId?: string;
+  /** API/reference documentation */
+  referenceDocId?: string;
+  /** Constraints/limitations documentation */
+  constraintsDocId?: string;
+}
+/** Surface support configuration for sandbox */
+interface ExampleSandboxSupport {
+  enabled: boolean;
+  modes: readonly ExampleSandboxMode[];
+}
+/** Surface support configuration for Studio */
+interface ExampleStudioSupport {
+  enabled: boolean;
+  /** If true, Studio can create a real project from this example via API. */
+  installable: boolean;
+}
+/** Surface support configuration for MCP */
+interface ExampleMcpSupport {
+  enabled: boolean;
+}
+/** Surface support configuration - where the example can be used */
+interface ExampleSurfaces {
+  /** Available as a template for new projects */
+  templates: boolean;
+  /** Sandbox/playground support */
+  sandbox: ExampleSandboxSupport;
+  /** ContractSpec Studio support */
+  studio: ExampleStudioSupport;
+  /** MCP (Model Context Protocol) support */
+  mcp: ExampleMcpSupport;
+}
+/** Package entrypoints for the example - maps to package.json exports */
+interface ExampleEntrypoints {
+  /** Package name in the workspace (e.g., @contractspec/example.saas-boilerplate) */
+  packageName: string;
+  /** Feature module entrypoint (e.g., ./saas-boilerplate.feature) */
+  feature?: string;
+  /** Blueprint entrypoint (e.g., ./blueprint) */
+  blueprint?: string;
+  /** Presentations entrypoint (e.g., ./presentations) */
+  presentations?: string;
+  /** Contracts/operations entrypoint (e.g., ./contracts) */
+  contracts?: string;
+  /** Handlers entrypoint (e.g., ./handlers) */
+  handlers?: string;
+  /** UI components entrypoint (e.g., ./ui) */
+  ui?: string;
+  /** Documentation entrypoint (e.g., ./docs) */
+  docs?: string;
+}
+/**
+ * Example metadata extending OwnerShipMeta.
+ * Provides standard spec identification plus example-specific fields.
+ */
+interface ExampleMeta extends OwnerShipMeta {
+  /** Example kind for categorization */
+  kind: ExampleKind;
+  /** Visibility level */
+  visibility: ExampleVisibility;
+  /** Short marketing summary (distinct from technical description) */
+  summary?: string;
+}
+/**
+ * ExampleSpec - Complete specification for a ContractSpec example.
+ *
+ * Integrates with AppBlueprintSpec for app configuration and
+ * FeatureModuleSpec for feature definitions.
+ *
+ * @example
+ * ```typescript
+ * const example: ExampleSpec = {
+ *   meta: {
+ *     key: 'saas-boilerplate',
+ *     version: '1.0.0',
+ *     title: 'SaaS Boilerplate',
+ *     description: 'Multi-tenant SaaS foundation.',
+ *     kind: 'template',
+ *     visibility: 'public',
+ *     stability: 'experimental',
+ *     owners: ['@saas-team'],
+ *     tags: ['saas', 'multi-tenant'],
+ *   },
+ *   surfaces: {
+ *     templates: true,
+ *     sandbox: { enabled: true, modes: ['playground', 'specs'] },
+ *     studio: { enabled: true, installable: true },
+ *     mcp: { enabled: true },
+ *   },
+ *   entrypoints: {
+ *     packageName: '@contractspec/example.saas-boilerplate',
+ *     feature: './saas-boilerplate.feature',
+ *   },
+ * };
+ * ```
+ */
+interface ExampleSpec {
+  /** Example metadata (identification, ownership, categorization) */
+  meta: ExampleMeta;
+  /** Documentation references */
+  docs?: ExampleDocumentation;
+  /** Surface support configuration */
+  surfaces: ExampleSurfaces;
+  /** Package entrypoints */
+  entrypoints: ExampleEntrypoints;
+  /**
+   * Inline or referenced AppBlueprintSpec.
+   * Use SpecPointer for external reference to a registered blueprint.
+   */
+  blueprint?: AppBlueprintSpec | SpecPointer;
+  /**
+   * Features included in this example.
+   * Can be inline FeatureModuleSpec objects or FeatureRef references.
+   */
+  features?: (FeatureModuleSpec | FeatureRef)[];
+}
+/** Check if a blueprint reference is a SpecPointer (external reference) */
+declare function isSpecPointer(ref: AppBlueprintSpec | SpecPointer | undefined): ref is SpecPointer;
+/** Check if a feature reference is a FeatureRef (external reference) */
+declare function isFeatureRef(ref: FeatureModuleSpec | FeatureRef): ref is FeatureRef;
+/** Check if a value is a valid ExampleKind */
+declare function isExampleKind(value: unknown): value is ExampleKind;
+/** Check if a value is a valid ExampleVisibility */
+declare function isExampleVisibility(value: unknown): value is ExampleVisibility;
+//#endregion
+export { ExampleDocumentation, ExampleEntrypoints, ExampleKind, ExampleKindEnum, ExampleMcpSupport, ExampleMeta, ExampleSandboxMode, ExampleSandboxModeEnum, ExampleSandboxSupport, ExampleSpec, ExampleStudioSupport, ExampleSurfaces, ExampleVisibility, ExampleVisibilityEnum, isExampleKind, isExampleVisibility, isFeatureRef, isSpecPointer };

package/dist/examples/types.js

@@ -0,0 +1,43 @@
+//#region src/examples/types.ts
+const ExampleKindEnum = {
+	Template: "template",
+	Workflow: "workflow",
+	Integration: "integration",
+	Knowledge: "knowledge",
+	Blueprint: "blueprint",
+	UI: "ui",
+	Script: "script",
+	Library: "library"
+};
+const ExampleVisibilityEnum = {
+	Public: "public",
+	Internal: "internal",
+	Experimental: "experimental"
+};
+const ExampleSandboxModeEnum = {
+	Playground: "playground",
+	Specs: "specs",
+	Builder: "builder",
+	Markdown: "markdown",
+	Evolution: "evolution"
+};
+/** Check if a blueprint reference is a SpecPointer (external reference) */
+function isSpecPointer(ref) {
+	if (!ref) return false;
+	return "key" in ref && !("meta" in ref);
+}
+/** Check if a feature reference is a FeatureRef (external reference) */
+function isFeatureRef(ref) {
+	return "key" in ref && !("meta" in ref);
+}
+/** Check if a value is a valid ExampleKind */
+function isExampleKind(value) {
+	return typeof value === "string" && Object.values(ExampleKindEnum).includes(value);
+}
+/** Check if a value is a valid ExampleVisibility */
+function isExampleVisibility(value) {
+	return typeof value === "string" && Object.values(ExampleVisibilityEnum).includes(value);
+}
+
+//#endregion
+export { ExampleKindEnum, ExampleSandboxModeEnum, ExampleVisibilityEnum, isExampleKind, isExampleVisibility, isFeatureRef, isSpecPointer };

package/dist/examples/validation.d.ts

@@ -0,0 +1,65 @@
+import { ExampleSpec } from "./types.js";
+
+//#region src/examples/validation.d.ts
+interface ExampleValidationError {
+  /** Example key if available */
+  exampleKey?: string;
+  /** Error message */
+  message: string;
+  /** Path within the spec where error occurred */
+  path?: string;
+  /** Error code for programmatic handling */
+  code?: string;
+}
+interface ExampleValidationWarning {
+  /** Example key if available */
+  exampleKey?: string;
+  /** Warning message */
+  message: string;
+  /** Path within the spec where warning applies */
+  path?: string;
+}
+type ValidateExamplesResult = {
+  ok: true;
+  examples: ExampleSpec[];
+} | {
+  ok: false;
+  errors: ExampleValidationError[];
+};
+interface ValidateExampleResult {
+  valid: boolean;
+  errors: ExampleValidationError[];
+  warnings: ExampleValidationWarning[];
+}
+/**
+ * Validate a single ExampleSpec.
+ *
+ * @param example - The example to validate
+ * @returns Validation result with errors and warnings
+ */
+declare function validateExample(example: unknown): ValidateExampleResult;
+/**
+ * Validate multiple examples, checking for duplicates.
+ *
+ * @param examples - Array of examples to validate
+ * @returns Validation result with all valid examples or errors
+ */
+declare function validateExamples(examples: ExampleSpec[]): ValidateExamplesResult;
+interface CrossValidationContext {
+  /** Available feature keys */
+  featureKeys?: Set<string>;
+  /** Available blueprint keys */
+  blueprintKeys?: Set<string>;
+  /** Available package names in workspace */
+  packageNames?: Set<string>;
+}
+/**
+ * Validate example references against external registries.
+ *
+ * @param example - Example to validate
+ * @param context - External context for cross-reference validation
+ * @returns Validation result with errors and warnings
+ */
+declare function validateExampleReferences(example: ExampleSpec, context: CrossValidationContext): ValidateExampleResult;
+//#endregion
+export { CrossValidationContext, ExampleValidationError, ExampleValidationWarning, ValidateExampleResult, ValidateExamplesResult, validateExample, validateExampleReferences, validateExamples };

package/dist/examples/validation.js

@@ -0,0 +1,144 @@
+import { safeParseExampleSpec } from "./schema.js";
+
+//#region src/examples/validation.ts
+/**
+* Validate a single ExampleSpec.
+*
+* @param example - The example to validate
+* @returns Validation result with errors and warnings
+*/
+function validateExample(example) {
+	const errors = [];
+	const warnings = [];
+	const parsed = safeParseExampleSpec(example);
+	if (!parsed.success) {
+		for (const issue of parsed.error.issues) errors.push({
+			exampleKey: example?.meta?.key,
+			message: issue.message,
+			path: issue.path.join("."),
+			code: issue.code
+		});
+		return {
+			valid: false,
+			errors,
+			warnings
+		};
+	}
+	const spec = parsed.data;
+	validateSemantics(spec, errors, warnings);
+	return {
+		valid: errors.length === 0,
+		errors,
+		warnings
+	};
+}
+function validateSemantics(spec, errors, warnings) {
+	const key = spec.meta.key;
+	if (!spec.entrypoints.packageName.startsWith("@")) warnings.push({
+		exampleKey: key,
+		message: "Package name should be scoped (e.g., @contractspec/example.name)",
+		path: "entrypoints.packageName"
+	});
+	if (spec.surfaces.studio.installable && !spec.surfaces.studio.enabled) errors.push({
+		exampleKey: key,
+		message: "Studio installable requires studio.enabled to be true",
+		path: "surfaces.studio",
+		code: "STUDIO_INSTALLABLE_REQUIRES_ENABLED"
+	});
+	if (spec.surfaces.sandbox.enabled && spec.surfaces.sandbox.modes.length === 0) warnings.push({
+		exampleKey: key,
+		message: "Sandbox is enabled but has no modes configured",
+		path: "surfaces.sandbox.modes"
+	});
+	if (spec.features && spec.features.length > 0 && !spec.entrypoints.feature) warnings.push({
+		exampleKey: key,
+		message: "Example has features but no feature entrypoint in entrypoints.feature",
+		path: "entrypoints.feature"
+	});
+	if (spec.blueprint && !spec.entrypoints.blueprint) warnings.push({
+		exampleKey: key,
+		message: "Example has blueprint but no blueprint entrypoint in entrypoints.blueprint",
+		path: "entrypoints.blueprint"
+	});
+	if (spec.meta.visibility === "public" && spec.meta.stability === "idea") warnings.push({
+		exampleKey: key,
+		message: "Public examples should not be in \"idea\" stability",
+		path: "meta.stability"
+	});
+}
+/**
+* Validate multiple examples, checking for duplicates.
+*
+* @param examples - Array of examples to validate
+* @returns Validation result with all valid examples or errors
+*/
+function validateExamples(examples) {
+	const errors = [];
+	const seen = /* @__PURE__ */ new Set();
+	const validExamples = [];
+	for (const example of examples) {
+		if (seen.has(example.meta.key)) {
+			errors.push({
+				exampleKey: example.meta.key,
+				message: `Duplicate example key: ${example.meta.key}`,
+				code: "DUPLICATE_KEY"
+			});
+			continue;
+		}
+		seen.add(example.meta.key);
+		const result = validateExample(example);
+		if (!result.valid) errors.push(...result.errors);
+		else validExamples.push(example);
+	}
+	if (errors.length > 0) return {
+		ok: false,
+		errors
+	};
+	return {
+		ok: true,
+		examples: validExamples
+	};
+}
+/**
+* Validate example references against external registries.
+*
+* @param example - Example to validate
+* @param context - External context for cross-reference validation
+* @returns Validation result with errors and warnings
+*/
+function validateExampleReferences(example, context) {
+	const errors = [];
+	const warnings = [];
+	const key = example.meta.key;
+	if (context.packageNames && !context.packageNames.has(example.entrypoints.packageName)) warnings.push({
+		exampleKey: key,
+		message: `Package "${example.entrypoints.packageName}" not found in workspace`,
+		path: "entrypoints.packageName"
+	});
+	if (example.features && context.featureKeys) {
+		for (const feature of example.features) if ("key" in feature && !("meta" in feature)) {
+			if (!context.featureKeys.has(feature.key)) warnings.push({
+				exampleKey: key,
+				message: `Feature "${feature.key}" not found in registry`,
+				path: "features"
+			});
+		}
+	}
+	if (example.blueprint && context.blueprintKeys) {
+		if ("key" in example.blueprint && !("meta" in example.blueprint)) {
+			if (!context.blueprintKeys.has(example.blueprint.key)) warnings.push({
+				exampleKey: key,
+				message: `Blueprint "${example.blueprint.key}" not found in registry`,
+				path: "blueprint"
+			});
+		}
+	}
+	return {
+		valid: errors.length === 0,
+		errors,
+		warnings
+	};
+}
+
+//#endregion
+export { validateExample, validateExampleReferences, validateExamples };

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.0.0',\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.0.0' },\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?: string;
+  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 { OpKind, OperationSpec } from "../operations/operation.js";
+import "../operations/index.js";
+import { HandlerCtx } from "../types.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: string;
+    kind: OpKind;
+  }, ctx: HandlerCtx): Promise<RuntimeContract | undefined> | RuntimeContract | undefined;
+}
+//#endregion
+export { RuntimeContract, SpecVariantResolver };