@contractspec/lib.contracts 1.44.0 → 1.45.0

package/dist/examples/schema.js

@@ -0,0 +1,125 @@
+import { z as z$1 } from "zod";
+
+//#region src/examples/schema.ts
+const ExampleKindSchema = z$1.enum([
+	"template",
+	"workflow",
+	"integration",
+	"knowledge",
+	"blueprint",
+	"ui",
+	"script",
+	"library"
+]);
+const ExampleVisibilitySchema = z$1.enum([
+	"public",
+	"internal",
+	"experimental"
+]);
+const ExampleSandboxModeSchema = z$1.enum([
+	"playground",
+	"specs",
+	"builder",
+	"markdown",
+	"evolution"
+]);
+const StabilitySchema = z$1.enum([
+	"idea",
+	"in_creation",
+	"experimental",
+	"beta",
+	"stable",
+	"deprecated"
+]);
+const ExampleDocumentationSchema = z$1.object({
+	rootDocId: z$1.string().optional(),
+	goalDocId: z$1.string().optional(),
+	usageDocId: z$1.string().optional(),
+	referenceDocId: z$1.string().optional(),
+	constraintsDocId: z$1.string().optional()
+});
+const ExampleSandboxSupportSchema = z$1.object({
+	enabled: z$1.boolean(),
+	modes: z$1.array(ExampleSandboxModeSchema)
+});
+const ExampleStudioSupportSchema = z$1.object({
+	enabled: z$1.boolean(),
+	installable: z$1.boolean()
+});
+const ExampleMcpSupportSchema = z$1.object({ enabled: z$1.boolean() });
+const ExampleSurfacesSchema = z$1.object({
+	templates: z$1.boolean(),
+	sandbox: ExampleSandboxSupportSchema,
+	studio: ExampleStudioSupportSchema,
+	mcp: ExampleMcpSupportSchema
+});
+const ExampleEntrypointsSchema = z$1.object({
+	packageName: z$1.string().min(1),
+	feature: z$1.string().optional(),
+	blueprint: z$1.string().optional(),
+	presentations: z$1.string().optional(),
+	contracts: z$1.string().optional(),
+	handlers: z$1.string().optional(),
+	ui: z$1.string().optional(),
+	docs: z$1.string().optional()
+});
+const ExampleMetaSchema = z$1.object({
+	version: z$1.string(),
+	key: z$1.string().min(1),
+	title: z$1.string().optional(),
+	description: z$1.string().min(1),
+	domain: z$1.string().optional(),
+	stability: StabilitySchema,
+	owners: z$1.array(z$1.string()),
+	tags: z$1.array(z$1.string()),
+	docId: z$1.array(z$1.string()).optional(),
+	kind: ExampleKindSchema,
+	visibility: ExampleVisibilitySchema,
+	summary: z$1.string().optional()
+});
+const SpecPointerSchema = z$1.object({
+	key: z$1.string().min(1),
+	version: z$1.string().optional()
+});
+const FeatureRefSchema = z$1.object({ key: z$1.string().min(1) });
+/**
+* Zod schema for validating ExampleSpec objects.
+*
+* Note: blueprint and features are loosely validated since they can be
+* inline specs or references. Full validation requires registry lookups.
+*/
+const ExampleSpecSchema = z$1.object({
+	meta: ExampleMetaSchema,
+	docs: ExampleDocumentationSchema.optional(),
+	surfaces: ExampleSurfacesSchema,
+	entrypoints: ExampleEntrypointsSchema,
+	blueprint: z$1.union([z$1.record(z$1.string(), z$1.unknown()), SpecPointerSchema]).optional(),
+	features: z$1.array(z$1.union([z$1.record(z$1.string(), z$1.unknown()), FeatureRefSchema])).optional()
+});
+/** Parse and validate an ExampleSpec, throwing on failure */
+function parseExampleSpec(data) {
+	return ExampleSpecSchema.parse(data);
+}
+/** Safely parse an ExampleSpec, returning result object */
+function safeParseExampleSpec(data) {
+	return ExampleSpecSchema.safeParse(data);
+}
+/** Parse and validate ExampleMeta */
+function parseExampleMeta(data) {
+	return ExampleMetaSchema.parse(data);
+}
+/** Parse and validate ExampleSurfaces */
+function parseExampleSurfaces(data) {
+	return ExampleSurfacesSchema.parse(data);
+}
+/** Parse and validate ExampleEntrypoints */
+function parseExampleEntrypoints(data) {
+	return ExampleEntrypointsSchema.parse(data);
+}
+/** Parse and validate ExampleDocumentation */
+function parseExampleDocumentation(data) {
+	return ExampleDocumentationSchema.parse(data);
+}
+
+//#endregion
+export { ExampleDocumentationSchema, ExampleEntrypointsSchema, ExampleKindSchema, ExampleMcpSupportSchema, ExampleMetaSchema, ExampleSandboxModeSchema, ExampleSandboxSupportSchema, ExampleSpecSchema, ExampleStudioSupportSchema, ExampleSurfacesSchema, ExampleVisibilitySchema, FeatureRefSchema, SpecPointerSchema, StabilitySchema, parseExampleDocumentation, parseExampleEntrypoints, parseExampleMeta, parseExampleSpec, parseExampleSurfaces, safeParseExampleSpec };

package/dist/examples/types.d.ts

@@ -0,0 +1,167 @@
+import { OwnerShipMeta } from "../ownership.js";
+import { AppBlueprintSpec, SpecPointer } from "../app-config/spec.js";
+import { FeatureModuleSpec, FeatureRef } from "../features/types.js";
+import "../features/index.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.js

@@ -13,7 +13,7 @@ const tech_contracts_experiments_DocBlocks = [{
 		"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"
+	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);
 

package/dist/experiments/evaluator.d.ts

@@ -4,7 +4,7 @@ import { ExperimentRegistry, ExperimentVariant } from "./spec.js";
 //#region src/experiments/evaluator.d.ts
 interface ExperimentContext {
   experiment: string;
-  version?: number;
+  version?: string;
   userId?: string | null;
   organizationId?: string | null;
   sessionId?: string | null;

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

@@ -1,7 +1,7 @@
 import { ResourceRefDescriptor } from "../resources.js";
-import { HandlerCtx } from "../types.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
@@ -9,7 +9,7 @@ type RuntimeContract = OperationSpec<AnySchemaModel, AnySchemaModel | ResourceRe
 interface SpecVariantResolver {
   resolve(operation: {
     name: string;
-    version: number;
+    version: string;
     kind: OpKind;
   }, ctx: HandlerCtx): Promise<RuntimeContract | undefined> | RuntimeContract | undefined;
 }

package/dist/experiments/spec.d.ts

@@ -1,12 +1,13 @@
 import { OwnerShipMeta } from "../ownership.js";
 import { PolicyRef } from "../policy/spec.js";
 import { TelemetryEventDef } from "../telemetry/spec.js";
+import { SpecContractRegistry } from "../registry.js";
 
 //#region src/experiments/spec.d.ts
 type ExperimentMeta = OwnerShipMeta;
 interface ExperimentRef {
   key: string;
-  version?: number;
+  version?: string;
 }
 type ExperimentOverrideType = 'dataView' | 'workflow' | 'theme' | 'policy' | 'presentation';
 interface ExperimentOverride {
@@ -14,7 +15,7 @@ interface ExperimentOverride {
   /** Target spec meta name (e.g., DataViewspec.meta.key). */
   target: string;
   /** Target version. Optional; evaluator may choose latest when omitted. */
-  version?: number;
+  version?: string;
   /** Optional configuration applied when this variant is active. */
   config?: Record<string, unknown>;
 }
@@ -57,7 +58,7 @@ interface SuccessMetric {
   key: string;
   telemetryEvent: {
     key: TelemetryEventDef['key'];
-    version: number;
+    version: string;
   };
   aggregation: MetricAggregation;
   target?: number;
@@ -71,11 +72,8 @@ interface ExperimentSpec {
   successMetrics?: SuccessMetric[];
   tags?: string[];
 }
-declare class ExperimentRegistry {
-  private readonly items;
-  register(spec: ExperimentSpec): this;
-  list(): ExperimentSpec[];
-  get(name: string, version?: number): ExperimentSpec | undefined;
+declare class ExperimentRegistry extends SpecContractRegistry<'experiment', ExperimentSpec> {
+  constructor(items?: ExperimentSpec[]);
 }
 declare function makeExperimentKey(meta: ExperimentMeta): string;
 //#endregion

package/dist/experiments/spec.js

@@ -1,28 +1,10 @@
+import { SpecContractRegistry } from "../registry.js";
+
 //#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;
+var ExperimentRegistry = class extends SpecContractRegistry {
+	constructor(items) {
+		super("experiment", items);
 	}
 };
 function makeExperimentKey(meta) {