@contractspec/lib.contracts 1.49.0 → 1.50.0

package/dist/app-config/lifecycle-contracts.d.ts

@@ -3,50 +3,50 @@ import { OperationSpecRegistry } from "../operations/registry.js";
 import "../operations/index.js";
 import { EventSpecMeta } from "../events.js";
 import "../index.js";
-import * as _contractspec_lib_schema392 from "@contractspec/lib.schema";
+import * as _contractspec_lib_schema167 from "@contractspec/lib.schema";
 import { SchemaModel } from "@contractspec/lib.schema";
 
 //#region src/app-config/lifecycle-contracts.d.ts
 declare const CreateTenantConfigDraftCommand: OperationSpec<SchemaModel<{
   tenantId: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema167.FieldType<string, string>;
     isOptional: false;
   };
   appId: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema167.FieldType<string, string>;
     isOptional: false;
   };
   blueprintName: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema167.FieldType<string, string>;
     isOptional: false;
   };
   blueprintVersion: {
-    type: _contractspec_lib_schema392.FieldType<number, number>;
+    type: _contractspec_lib_schema167.FieldType<number, number>;
     isOptional: false;
   };
   environment: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema167.FieldType<string, string>;
     isOptional: true;
   };
   fromVersion: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema167.FieldType<string, string>;
     isOptional: true;
   };
   createdBy: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema167.FieldType<string, string>;
     isOptional: false;
   };
 }>, SchemaModel<{
   version: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema167.FieldType<string, string>;
     isOptional: false;
   };
   status: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema167.FieldType<string, string>;
     isOptional: false;
   };
   createdAt: {
-    type: _contractspec_lib_schema392.FieldType<Date, string>;
+    type: _contractspec_lib_schema167.FieldType<Date, string>;
     isOptional: false;
   };
 }>, {
@@ -55,32 +55,32 @@ declare const CreateTenantConfigDraftCommand: OperationSpec<SchemaModel<{
 }[]>;
 declare const PromoteTenantConfigToPreviewCommand: OperationSpec<SchemaModel<{
   tenantId: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema167.FieldType<string, string>;
     isOptional: false;
   };
   appId: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema167.FieldType<string, string>;
     isOptional: false;
   };
   version: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema167.FieldType<string, string>;
     isOptional: false;
   };
   promotedBy: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema167.FieldType<string, string>;
     isOptional: false;
   };
 }>, SchemaModel<{
   version: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema167.FieldType<string, string>;
     isOptional: false;
   };
   status: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema167.FieldType<string, string>;
     isOptional: false;
   };
   warnings: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema167.FieldType<string, string>;
     isOptional: true;
     isArray: true;
   };
@@ -90,44 +90,44 @@ declare const PromoteTenantConfigToPreviewCommand: OperationSpec<SchemaModel<{
 }[]>;
 declare const PublishTenantConfigCommand: OperationSpec<SchemaModel<{
   tenantId: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema167.FieldType<string, string>;
     isOptional: false;
   };
   appId: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema167.FieldType<string, string>;
     isOptional: false;
   };
   version: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema167.FieldType<string, string>;
     isOptional: false;
   };
   environment: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema167.FieldType<string, string>;
     isOptional: true;
   };
   publishedBy: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema167.FieldType<string, string>;
     isOptional: false;
   };
   changeSummary: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema167.FieldType<string, string>;
     isOptional: true;
   };
 }>, SchemaModel<{
   version: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema167.FieldType<string, string>;
     isOptional: false;
   };
   status: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema167.FieldType<string, string>;
     isOptional: false;
   };
   previousVersion: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema167.FieldType<string, string>;
     isOptional: true;
   };
   publishedAt: {
-    type: _contractspec_lib_schema392.FieldType<Date, string>;
+    type: _contractspec_lib_schema167.FieldType<Date, string>;
     isOptional: false;
   };
 }>, {
@@ -136,40 +136,40 @@ declare const PublishTenantConfigCommand: OperationSpec<SchemaModel<{
 }[]>;
 declare const RollbackTenantConfigCommand: OperationSpec<SchemaModel<{
   tenantId: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema167.FieldType<string, string>;
     isOptional: false;
   };
   appId: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema167.FieldType<string, string>;
     isOptional: false;
   };
   toVersion: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema167.FieldType<string, string>;
     isOptional: false;
   };
   environment: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema167.FieldType<string, string>;
     isOptional: true;
   };
   rolledBackBy: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema167.FieldType<string, string>;
     isOptional: false;
   };
   reason: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema167.FieldType<string, string>;
     isOptional: false;
   };
 }>, SchemaModel<{
   newVersion: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema167.FieldType<string, string>;
     isOptional: false;
   };
   status: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema167.FieldType<string, string>;
     isOptional: false;
   };
   rolledBackFrom: {
-    type: _contractspec_lib_schema392.FieldType<number, number>;
+    type: _contractspec_lib_schema167.FieldType<number, number>;
     isOptional: false;
   };
 }>, {
@@ -178,22 +178,22 @@ declare const RollbackTenantConfigCommand: OperationSpec<SchemaModel<{
 }[]>;
 declare const ListTenantConfigVersionsQuery: OperationSpec<SchemaModel<{
   tenantId: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema167.FieldType<string, string>;
     isOptional: false;
   };
   appId: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema167.FieldType<string, string>;
     isOptional: false;
   };
 }>, SchemaModel<{
   versions: {
     type: SchemaModel<{
       meta: {
-        type: _contractspec_lib_schema392.FieldType<Record<string, unknown>, Record<string, unknown>>;
+        type: _contractspec_lib_schema167.FieldType<Record<string, unknown>, Record<string, unknown>>;
         isOptional: false;
       };
       config: {
-        type: _contractspec_lib_schema392.FieldType<Record<string, unknown>, Record<string, unknown>>;
+        type: _contractspec_lib_schema167.FieldType<Record<string, unknown>, Record<string, unknown>>;
         isOptional: false;
       };
     }>;
@@ -203,35 +203,35 @@ declare const ListTenantConfigVersionsQuery: OperationSpec<SchemaModel<{
   transitions: {
     type: SchemaModel<{
       tenantId: {
-        type: _contractspec_lib_schema392.FieldType<string, string>;
+        type: _contractspec_lib_schema167.FieldType<string, string>;
         isOptional: false;
       };
       appId: {
-        type: _contractspec_lib_schema392.FieldType<string, string>;
+        type: _contractspec_lib_schema167.FieldType<string, string>;
         isOptional: false;
       };
       fromStatus: {
-        type: _contractspec_lib_schema392.FieldType<string, string>;
+        type: _contractspec_lib_schema167.FieldType<string, string>;
         isOptional: false;
       };
       toStatus: {
-        type: _contractspec_lib_schema392.FieldType<string, string>;
+        type: _contractspec_lib_schema167.FieldType<string, string>;
         isOptional: false;
       };
       version: {
-        type: _contractspec_lib_schema392.FieldType<string, string>;
+        type: _contractspec_lib_schema167.FieldType<string, string>;
         isOptional: false;
       };
       timestamp: {
-        type: _contractspec_lib_schema392.FieldType<Date, string>;
+        type: _contractspec_lib_schema167.FieldType<Date, string>;
         isOptional: false;
       };
       actor: {
-        type: _contractspec_lib_schema392.FieldType<string, string>;
+        type: _contractspec_lib_schema167.FieldType<string, string>;
         isOptional: false;
       };
       reason: {
-        type: _contractspec_lib_schema392.FieldType<string, string>;
+        type: _contractspec_lib_schema167.FieldType<string, string>;
         isOptional: true;
       };
     }>;
@@ -241,26 +241,26 @@ declare const ListTenantConfigVersionsQuery: OperationSpec<SchemaModel<{
 }>, undefined>;
 declare const GetTenantConfigVersionQuery: OperationSpec<SchemaModel<{
   tenantId: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema167.FieldType<string, string>;
     isOptional: false;
   };
   appId: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema167.FieldType<string, string>;
     isOptional: false;
   };
   version: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema167.FieldType<string, string>;
     isOptional: false;
   };
 }>, SchemaModel<{
   version: {
     type: SchemaModel<{
       meta: {
-        type: _contractspec_lib_schema392.FieldType<Record<string, unknown>, Record<string, unknown>>;
+        type: _contractspec_lib_schema167.FieldType<Record<string, unknown>, Record<string, unknown>>;
         isOptional: false;
       };
       config: {
-        type: _contractspec_lib_schema392.FieldType<Record<string, unknown>, Record<string, unknown>>;
+        type: _contractspec_lib_schema167.FieldType<Record<string, unknown>, Record<string, unknown>>;
         isOptional: false;
       };
     }>;

package/dist/capabilities/capabilities.d.ts

@@ -1,28 +1,51 @@
 import { OwnerShipMeta } from "../ownership.js";
+import { VersionedSpecRef } from "../versioning/refs.js";
 
 //#region src/capabilities/capabilities.d.ts
+/** Classification of capability types. */
 type CapabilityKind = 'api' | 'event' | 'data' | 'ui' | 'integration';
+/** Surfaces where capabilities can be exposed or consumed. */
 type CapabilitySurface = 'operation' | 'event' | 'workflow' | 'presentation' | 'resource';
+/**
+ * Reference to a capability on a specific surface.
+ * Extends VersionedSpecRef with surface and description context.
+ */
 interface CapabilitySurfaceRef {
+  /** The surface type where this capability is exposed. */
   surface: CapabilitySurface;
+  /** Unique key identifying the capability. */
   key: string;
+  /** Semantic version of the capability. */
   version: string;
+  /** Optional description of what this capability provides. */
   description?: string;
 }
+/** Metadata for a capability spec, extending ownership with kind. */
 interface CapabilityMeta extends OwnerShipMeta {
+  /** The kind/category of this capability. */
   kind: CapabilityKind;
 }
+/**
+ * Requirement for a capability dependency.
+ * Used to declare what capabilities a spec needs.
+ */
 interface CapabilityRequirement {
+  /** Unique key of the required capability. */
   key: string;
+  /** Optional specific version required. */
   version?: string;
+  /** Optional kind filter for the requirement. */
   kind?: CapabilityKind;
+  /** If true, the requirement is optional and won't block if missing. */
   optional?: boolean;
+  /** Human-readable reason why this capability is required. */
   reason?: string;
 }
-interface CapabilityRef {
-  key: string;
-  version: string;
-}
+/**
+ * Reference to a capability spec.
+ * Uses key and version to identify a specific capability.
+ */
+type CapabilityRef = VersionedSpecRef;
 interface CapabilitySpec {
   meta: CapabilityMeta;
   provides?: CapabilitySurfaceRef[];

package/dist/contract-registry/schemas.d.ts

@@ -46,12 +46,12 @@ declare const ContractRegistryItemSchema: z.ZodObject<{
   description: z.ZodString;
   meta: z.ZodObject<{
     stability: z.ZodEnum<{
+      deprecated: "deprecated";
       idea: "idea";
       in_creation: "in_creation";
       experimental: "experimental";
       beta: "beta";
       stable: "stable";
-      deprecated: "deprecated";
     }>;
     owners: z.ZodDefault<z.ZodArray<z.ZodString>>;
     tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
@@ -95,12 +95,12 @@ declare const ContractRegistryManifestSchema: z.ZodObject<{
     description: z.ZodString;
     meta: z.ZodObject<{
       stability: z.ZodEnum<{
+        deprecated: "deprecated";
         idea: "idea";
         in_creation: "in_creation";
         experimental: "experimental";
         beta: "beta";
         stable: "stable";
-        deprecated: "deprecated";
       }>;
       owners: z.ZodDefault<z.ZodArray<z.ZodString>>;
       tags: z.ZodDefault<z.ZodArray<z.ZodString>>;

package/dist/events.d.ts

@@ -4,42 +4,102 @@ import { SpecContractRegistry } from "./registry.js";
 import { AnySchemaModel } from "@contractspec/lib.schema";
 
 //#region src/events.d.ts
+
+/**
+ * Metadata for an event specification.
+ * Extends OwnerShipMeta with event-specific documentation.
+ */
 interface EventSpecMeta extends Omit<OwnerShipMeta, 'docId'> {
-  /** Doc block(s) for this operation. */
+  /** Associated DocBlock identifiers for this event. */
   docId?: DocId[];
 }
 /**
- * Typed event specification. Declare once, validate payloads at publish time,
- * and guard emissions via the contracts runtime.
+ * Typed event specification.
+ *
+ * Declare once, validate payloads at publish time, and guard emissions
+ * via the contracts runtime. Events are the backbone of event-driven
+ * architectures in ContractSpec.
+ *
+ * @typeParam T - The SchemaModel type defining the event payload structure
  */
 interface EventSpec<T extends AnySchemaModel> {
+  /** Event metadata including key, version, and ownership. */
   meta: EventSpecMeta;
-  /** JSON-like paths to redact from logs/exports. */
+  /**
+   * JSON paths to PII fields that should be redacted in logs/exports.
+   * @example ['email', 'user.phone', 'billing.address']
+   */
   pii?: string[];
   /** Event payload schema from @contractspec/lib.schema. */
   payload: T;
 }
+/**
+ * Type alias for any EventSpec regardless of payload type.
+ * Useful for collections and registries.
+ */
 type AnyEventSpec<T extends AnySchemaModel = AnySchemaModel> = EventSpec<T>;
-/** Identity function to keep type inference when declaring events. */
+/**
+ * Identity function to define an event spec with full type inference.
+ *
+ * @param e - The event specification
+ * @returns The same event specification with preserved types
+ *
+ * @example
+ * ```typescript
+ * const MyEvent = defineEvent({
+ *   meta: { key: 'my.event', version: '1.0.0', ... },
+ *   payload: myPayloadSchema,
+ * });
+ * ```
+ */
 declare function defineEvent<T extends AnySchemaModel>(e: EventSpec<T>): EventSpec<T>;
+/**
+ * Wrapper for a published event with metadata.
+ *
+ * Used when events are serialized for transport or storage.
+ * Contains the validated payload plus envelope metadata.
+ *
+ * @typeParam T - The payload type
+ */
 interface EventEnvelope<T> {
-  /** Unique identifier for the published event (UUID recommended). */
+  /** Unique identifier for this event instance (UUID recommended). */
   id: string;
-  /** ISO timestamp when the event occurred. */
+  /** ISO 8601 timestamp when the event occurred. */
   occurredAt: string;
-  /** Optional trace identifier for correlating across services. */
+  /** Trace identifier for correlating across services. */
   traceId?: string;
-  /** Event name as published (should match spec.name). */
+  /** Event key (should match spec.meta.key). */
   key: string;
-  /** Event version as published (should match spec.version). */
+  /** Event version (should match spec.meta.version). */
   version: string;
-  /** Validated payload. */
+  /** Validated event payload. */
   payload: T;
 }
+/**
+ * Template literal type for event keys.
+ * Format: "key.vversion" (e.g., "user.created.v1.0.0")
+ */
 type EventKey = `${string}.v${string}`;
-/** Build a stable string key for an event name/version pair. */
+/**
+ * Builds a stable string key for an event name/version pair.
+ *
+ * @param key - The event key (e.g., "user.created")
+ * @param version - The event version (e.g., "1.0.0")
+ * @returns A string in format "key.vversion"
+ *
+ * @example
+ * ```typescript
+ * const key = eventKey('user.created', '1.0.0');
+ * // "user.created.v1.0.0"
+ * ```
+ */
 declare const eventKey: (key: string, version: string) => EventKey;
-/** In-memory registry for EventSpec. */
+/**
+ * In-memory registry for EventSpec instances.
+ *
+ * Provides registration, lookup, and listing of event specifications.
+ * Used by the contracts runtime to validate event emissions.
+ */
 declare class EventRegistry extends SpecContractRegistry<'event', AnyEventSpec> {
   constructor(items?: AnyEventSpec[]);
 }

package/dist/events.js

@@ -2,13 +2,43 @@ import { SpecContractRegistry } from "./registry.js";
 import "@contractspec/lib.schema";
 
 //#region src/events.ts
-/** Identity function to keep type inference when declaring events. */
+/**
+* Identity function to define an event spec with full type inference.
+*
+* @param e - The event specification
+* @returns The same event specification with preserved types
+*
+* @example
+* ```typescript
+* const MyEvent = defineEvent({
+*   meta: { key: 'my.event', version: '1.0.0', ... },
+*   payload: myPayloadSchema,
+* });
+* ```
+*/
 function defineEvent(e) {
 	return e;
 }
-/** Build a stable string key for an event name/version pair. */
+/**
+* Builds a stable string key for an event name/version pair.
+*
+* @param key - The event key (e.g., "user.created")
+* @param version - The event version (e.g., "1.0.0")
+* @returns A string in format "key.vversion"
+*
+* @example
+* ```typescript
+* const key = eventKey('user.created', '1.0.0');
+* // "user.created.v1.0.0"
+* ```
+*/
 const eventKey = (key, version) => `${key}.v${version}`;
-/** In-memory registry for EventSpec. */
+/**
+* In-memory registry for EventSpec instances.
+*
+* Provides registration, lookup, and listing of event specifications.
+* Used by the contracts runtime to validate event emissions.
+*/
 var EventRegistry = class extends SpecContractRegistry {
 	constructor(items) {
 		super("event", items);

package/dist/examples/schema.d.ts

@@ -3,10 +3,10 @@ import { z as z$1 } from "zod";
 
 //#region src/examples/schema.d.ts
 declare const ExampleKindSchema: z$1.ZodEnum<{
+  knowledge: "knowledge";
   library: "library";
   workflow: "workflow";
   integration: "integration";
-  knowledge: "knowledge";
   template: "template";
   blueprint: "blueprint";
   ui: "ui";
@@ -25,12 +25,12 @@ declare const ExampleSandboxModeSchema: z$1.ZodEnum<{
   evolution: "evolution";
 }>;
 declare const StabilitySchema: z$1.ZodEnum<{
+  deprecated: "deprecated";
   idea: "idea";
   in_creation: "in_creation";
   experimental: "experimental";
   beta: "beta";
   stable: "stable";
-  deprecated: "deprecated";
 }>;
 declare const ExampleDocumentationSchema: z$1.ZodObject<{
   rootDocId: z$1.ZodOptional<z$1.ZodString>;
@@ -93,21 +93,21 @@ declare const ExampleMetaSchema: z$1.ZodObject<{
   description: z$1.ZodString;
   domain: z$1.ZodOptional<z$1.ZodString>;
   stability: z$1.ZodEnum<{
+    deprecated: "deprecated";
     idea: "idea";
     in_creation: "in_creation";
     experimental: "experimental";
     beta: "beta";
     stable: "stable";
-    deprecated: "deprecated";
   }>;
   owners: z$1.ZodArray<z$1.ZodString>;
   tags: z$1.ZodArray<z$1.ZodString>;
   docId: z$1.ZodOptional<z$1.ZodArray<z$1.ZodString>>;
   kind: z$1.ZodEnum<{
+    knowledge: "knowledge";
     library: "library";
     workflow: "workflow";
     integration: "integration";
-    knowledge: "knowledge";
     template: "template";
     blueprint: "blueprint";
     ui: "ui";
@@ -141,21 +141,21 @@ declare const ExampleSpecSchema: z$1.ZodObject<{
     description: z$1.ZodString;
     domain: z$1.ZodOptional<z$1.ZodString>;
     stability: z$1.ZodEnum<{
+      deprecated: "deprecated";
       idea: "idea";
       in_creation: "in_creation";
       experimental: "experimental";
       beta: "beta";
       stable: "stable";
-      deprecated: "deprecated";
     }>;
     owners: z$1.ZodArray<z$1.ZodString>;
     tags: z$1.ZodArray<z$1.ZodString>;
     docId: z$1.ZodOptional<z$1.ZodArray<z$1.ZodString>>;
     kind: z$1.ZodEnum<{
+      knowledge: "knowledge";
       library: "library";
       workflow: "workflow";
       integration: "integration";
-      knowledge: "knowledge";
       template: "template";
       blueprint: "blueprint";
       ui: "ui";
@@ -221,10 +221,10 @@ declare function safeParseExampleSpec(data: unknown): z$1.ZodSafeParseResult<{
     version: string;
     key: string;
     description: string;
-    stability: "idea" | "in_creation" | "experimental" | "beta" | "stable" | "deprecated";
+    stability: "deprecated" | "idea" | "in_creation" | "experimental" | "beta" | "stable";
     owners: string[];
     tags: string[];
-    kind: "library" | "workflow" | "integration" | "knowledge" | "template" | "blueprint" | "ui" | "script";
+    kind: "knowledge" | "library" | "workflow" | "integration" | "template" | "blueprint" | "ui" | "script";
     visibility: "experimental" | "public" | "internal";
     title?: string | undefined;
     domain?: string | undefined;

package/dist/experiments/spec.d.ts

@@ -1,14 +1,17 @@
 import { OwnerShipMeta } from "../ownership.js";
+import { OptionalVersionedSpecRef } from "../versioning/refs.js";
 import { PolicyRef } from "../policy/spec.js";
 import { TelemetryEventDef } from "../telemetry/spec.js";
 import { SpecContractRegistry } from "../registry.js";
 
 //#region src/experiments/spec.d.ts
+/** Metadata for an experiment spec. */
 type ExperimentMeta = OwnerShipMeta;
-interface ExperimentRef {
-  key: string;
-  version?: string;
-}
+/**
+ * Reference to an experiment spec.
+ * Version is optional; when omitted, refers to the latest version.
+ */
+type ExperimentRef = OptionalVersionedSpecRef;
 type ExperimentOverrideType = 'dataView' | 'workflow' | 'theme' | 'policy' | 'presentation';
 interface ExperimentOverride {
   type: ExperimentOverrideType;