@contractspec/lib.feature-flags 1.48.1 → 1.50.0

package/dist/contracts/src/capabilities/capabilities.d.ts

@@ -1,28 +1,51 @@
 import { OwnerShipMeta } from "../ownership.js";
+import { VersionedSpecRef } from "../versioning/refs.js";
 
 //#region ../contracts/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/contracts/src/capabilities/capabilities.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"capabilities.d.ts","names":[],"sources":["../../../../../contracts/src/capabilities/capabilities.ts"],"sourcesContent":[],"mappings":";;;KAGY,cAAA;KAEA,iBAAA;AAFA,UASK,oBAAA,CATS;EAEd,OAAA,EAQD,iBARkB;EAOZ,GAAA,EAAA,MAAA;EAOA,OAAA,EAAA,MAAA;EAIA,WAAA,CAAA,EAAA,MAAA;AAQjB;AAKiB,UAjBA,cAAA,SAAuB,aAiBT,CAAA;EACvB,IAAA,EAjBA,cAiBA;;AAEK,UAhBI,qBAAA,CAgBJ;EAAqB,GAAA,EAAA,MAAA;;SAbzB;;;;UAKQ,aAAA;;;;UAKA,cAAA;QACT;aACK;aACA"}
+{"version":3,"file":"capabilities.d.ts","names":[],"sources":["../../../../../contracts/src/capabilities/capabilities.ts"],"sourcesContent":[],"mappings":";;;;;KAKY,cAAA;AAAZ;AAGY,KAAA,iBAAA,GAAiB,WAAA,GAAA,OAAA,GAAA,UAAA,GAAA,cAAA,GAAA,UAAA;AAW7B;AAYA;AASA;AAiBA;AAEiB,UAxCA,oBAAA,CAwCc;EACvB;EACK,OAAA,EAxCF,iBAwCE;EACA;EAAqB,GAAA,EAAA,MAAA;;;;;;;UA/BjB,cAAA,SAAuB;;QAEhC;;;;;;UAOS,qBAAA;;;;;;SAMR;;;;;;;;;;KAWG,aAAA,GAAgB;UAEX,cAAA;QACT;aACK;aACA"}

package/dist/contracts/src/data-views/index.d.ts

@@ -1,3 +1,4 @@
+import { DataViewRef } from "../features/types.js";
 import "./types.js";
 import "./spec.js";
 import "./registry.js";

package/dist/contracts/src/data-views/spec.d.ts

@@ -1,2 +1,3 @@
 import "../experiments/spec.js";
+import { DataViewRef } from "../features/types.js";
 import "./types.js";

package/dist/contracts/src/events.d.ts

@@ -5,17 +5,31 @@ import { OwnerShipMeta } from "./ownership.js";
 import "./registry.js";
 
 //#region ../contracts/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;

package/dist/contracts/src/events.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"events.d.ts","names":[],"sources":["../../../../contracts/src/events.ts"],"sourcesContent":[],"mappings":";;;;;;;UAKiB,aAAA,SAAsB,KAAK;;UAElC;AAFV;;;;;AASiB,UAAA,SAAS,CAAA,UAAW,cAAX,CAAA,CAAA;EAAW,IAAA,EAC7B,aAD6B;EAC7B;EAIG,GAAA,CAAA,EAAA,MAAA,EAAA;EAAC;WAAD"}
+{"version":3,"file":"events.d.ts","names":[],"sources":["../../../../contracts/src/events.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;UAgDiB,aAAA,SAAsB,KAAK;;UAElC;;;;;;;;;;;UAYO,oBAAoB;;QAE7B;;;;;;;WAOG"}

package/dist/contracts/src/experiments/spec.d.ts

@@ -1,13 +1,16 @@
 import "../ownership.js";
+import { OptionalVersionedSpecRef } from "../versioning/refs.js";
 import "../policy/spec.js";
 import "../telemetry/spec.js";
 import "../registry.js";
 
 //#region ../contracts/src/experiments/spec.d.ts
-interface ExperimentRef {
-  key: string;
-  version?: string;
-}
+
+/**
+ * Reference to an experiment spec.
+ * Version is optional; when omitted, refers to the latest version.
+ */
+type ExperimentRef = OptionalVersionedSpecRef;
 //#endregion
 export { ExperimentRef };
 //# sourceMappingURL=spec.d.ts.map

package/dist/contracts/src/experiments/spec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"spec.d.ts","names":[],"sources":["../../../../../contracts/src/experiments/spec.ts"],"sourcesContent":[],"mappings":";;;;;;UAOiB,aAAA;EAAA,GAAA,EAAA,MAAA"}
+{"version":3,"file":"spec.d.ts","names":[],"sources":["../../../../../contracts/src/experiments/spec.ts"],"sourcesContent":[],"mappings":";;;;;;;;AAaA;;;;KAAY,aAAA,GAAgB"}

package/dist/contracts/src/features/index.d.ts

@@ -1,4 +1,4 @@
-import { EventRef, FeatureModuleMeta, FeatureModuleSpec, OpRef, PresentationRef } from "./types.js";
+import { DataViewRef, EventRef, FeatureModuleMeta, FeatureModuleSpec, FormRef, OpRef, PresentationRef } from "./types.js";
 import "./registry.js";
 import "./install.js";
 import "./validation.js";

package/dist/contracts/src/features/types.d.ts

@@ -1,5 +1,6 @@
 import { PresentationTarget } from "../presentations/presentations.js";
 import { OwnerShipMeta } from "../ownership.js";
+import { VersionedSpecRef } from "../versioning/refs.js";
 import { CapabilityRef, CapabilityRequirement } from "../capabilities/capabilities.js";
 import "../capabilities/index.js";
 import { ExperimentRef } from "../experiments/spec.js";
@@ -9,38 +10,31 @@ import "../operations/index.js";
 //#region ../contracts/src/features/types.d.ts
 /** Minimal metadata to identify and categorize a feature module. */
 type FeatureModuleMeta = OwnerShipMeta;
-interface OpRef {
-  /** Operation key (OperationSpec.meta.key). */
-  key: string;
-  /** Operation version (OperationSpec.meta.version). */
-  version: string;
-}
-interface EventRef {
-  /** Event key. */
-  key: string;
-  /** Event version. */
-  version: string;
-}
-interface PresentationRef {
-  /** Presentation key. */
-  key: string;
-  /** Presentation version. */
-  version: string;
-}
+/**
+ * Reference to an operation spec.
+ * Uses key (OperationSpec.meta.key) and version (OperationSpec.meta.version).
+ */
+type OpRef = VersionedSpecRef;
+/**
+ * Reference to an event spec.
+ * Uses key (EventSpec.meta.key) and version (EventSpec.meta.version).
+ */
+type EventRef = VersionedSpecRef;
+/**
+ * Reference to a presentation spec.
+ * Uses key (PresentationSpec.meta.key) and version (PresentationSpec.meta.version).
+ */
+type PresentationRef = VersionedSpecRef;
 /**
  * Reference to a data view spec.
+ * Uses key (DataViewSpec.meta.key) and version (DataViewSpec.meta.version).
  */
-interface DataViewRef {
-  key: string;
-  version: string;
-}
+type DataViewRef = VersionedSpecRef;
 /**
  * Reference to a form spec.
+ * Uses key (FormSpec.meta.key) and version (FormSpec.meta.version).
  */
-interface FormRef {
-  key: string;
-  version: string;
-}
+type FormRef = VersionedSpecRef;
 /** Group operations/events/presentations into an installable feature. */
 interface FeatureModuleSpec {
   meta: FeatureModuleMeta;
@@ -82,5 +76,5 @@ interface FeatureModuleSpec {
   forms?: FormRef[];
 }
 //#endregion
-export { EventRef, FeatureModuleMeta, FeatureModuleSpec, OpRef, PresentationRef };
+export { DataViewRef, EventRef, FeatureModuleMeta, FeatureModuleSpec, FormRef, OpRef, PresentationRef };
 //# sourceMappingURL=types.d.ts.map

package/dist/contracts/src/features/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","names":[],"sources":["../../../../../contracts/src/features/types.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;KAOY,iBAAA,GAAoB;UAEf,KAAA;;EAFL,GAAA,EAAA,MAAA;EAEK;EAOA,OAAA,EAAA,MAAQ;AAOzB;AAUiB,UAjBA,QAAA,CAiBW;EAQX;EAMA,GAAA,EAAA,MAAA;EACT;EAEO,OAAA,EAAA,MAAA;;AAIG,UA/BD,eAAA,CA+BC;EAEF;EAGD,GAAA,EAAA,MAAA;EACA;EAGY,OAAA,EAAA,MAAA;;;;;AAqBjB,UAnDO,WAAA,CAmDP;EAAO,GAAA,EAAA,MAAA;;;;;;UA3CA,OAAA;;;;;UAMA,iBAAA;QACT;;eAEO;;WAEJ;;kBAEO;;gBAEF;;;eAGD;eACA;;;;QAGY;UAAa;;;;;;;;;aAQ3B;;;;;;oBAOO;;cAGN;;UAGJ"}
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../../../../contracts/src/features/types.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;KAQY,iBAAA,GAAoB;;;AAAhC;AAMA;AAMY,KANA,KAAA,GAAQ,gBAMG;AAMvB;AAMA;AAMA;AAGA;AACQ,KAtBI,QAAA,GAAW,gBAsBf;;;;;AAWO,KA3BH,eAAA,GAAkB,gBA2Bf;;;;;AAmBK,KAxCR,WAAA,GAAc,gBAwCN;;;;;KAlCR,OAAA,GAAU;;UAGL,iBAAA;QACT;;eAEO;;WAEJ;;kBAEO;;gBAEF;;;eAGD;eACA;;;;QAGY;UAAa;;;;;;;;;aAQ3B;;;;;;oBAOO;;cAGN;;UAGJ"}

package/dist/contracts/src/index.d.ts

@@ -4,6 +4,7 @@ import { DocId } from "./docs/registry.js";
 import "./docs/index.js";
 import { Owner, OwnerShipMeta, OwnersEnum, Stability, StabilityEnum, Tag, TagsEnum } from "./ownership.js";
 import "./registry-utils.js";
+import { OptionalVersionedSpecRef, VersionedSpecRef } from "./versioning/refs.js";
 import { PolicyRef } from "./policy/spec.js";
 import "./telemetry/index.js";
 import { CapabilityKind, CapabilityMeta, CapabilityRef, CapabilityRequirement, CapabilitySpec, CapabilitySurface, CapabilitySurfaceRef } from "./capabilities/capabilities.js";
@@ -14,7 +15,7 @@ import { TestSpecRef } from "./tests/spec.js";
 import { EmitDecl, EmitDeclInline, EmitDeclRef, ImplementationRef, ImplementationType, OpKind, OperationSpec, OperationSpecMeta, TelemetryTrigger } from "./operations/operation.js";
 import "./install.js";
 import "./operations/index.js";
-import { EventRef, FeatureModuleMeta, FeatureModuleSpec, OpRef, PresentationRef } from "./features/types.js";
+import { DataViewRef, EventRef, FeatureModuleMeta, FeatureModuleSpec, FormRef, OpRef, PresentationRef } from "./features/types.js";
 import "./presentations/index.js";
 import "./features/index.js";
 import "./data-views/index.js";
@@ -48,4 +49,5 @@ import "./workflow/index.js";
 import "./schema-to-markdown.js";
 import "./llm/index.js";
 import "./app-config/validation.js";
-import "./examples/index.js";
+import "./examples/index.js";
+import "./serialization/index.js";

package/dist/contracts/src/ownership.d.ts

@@ -2,58 +2,161 @@ import { DocId } from "./docs/registry.js";
 import "./docs/index.js";
 
 //#region ../contracts/src/ownership.d.ts
+
+/**
+ * Lifecycle stability stages for specs.
+ *
+ * Specs progress through these stages as they mature:
+ * - `idea`: Initial concept, not implemented
+ * - `in_creation`: Currently being built
+ * - `experimental`: Working but may change significantly
+ * - `beta`: Feature-complete, seeking feedback
+ * - `stable`: Production-ready, breaking changes require major version bump
+ * - `deprecated`: Scheduled for removal, use alternatives
+ */
 declare const StabilityEnum: {
+  /** Initial concept, not yet implemented. */
   readonly Idea: "idea";
+  /** Currently being built, not ready for use. */
   readonly InCreation: "in_creation";
+  /** Working but unstable, may change significantly. */
   readonly Experimental: "experimental";
+  /** Feature-complete, seeking feedback before stabilization. */
   readonly Beta: "beta";
+  /** Production-ready, follows semantic versioning. */
   readonly Stable: "stable";
+  /** Scheduled for removal, use alternatives. */
   readonly Deprecated: "deprecated";
 };
+/** Stability level for a spec's lifecycle stage. */
 type Stability = (typeof StabilityEnum)[keyof typeof StabilityEnum];
+/**
+ * Curated owner identifiers for business/product ownership.
+ *
+ * Used for CODEOWNERS, on-call routing, and approval workflows.
+ * Custom owner strings are also allowed for flexibility.
+ */
 declare const OwnersEnum: {
+  /** Core platform team. */
   readonly PlatformCore: "platform.core";
+  /** Sigil/auth team. */
   readonly PlatformSigil: "platform.sigil";
+  /** Marketplace team. */
   readonly PlatformMarketplace: "platform.marketplace";
+  /** Messaging/notifications team. */
   readonly PlatformMessaging: "platform.messaging";
+  /** Content/CMS team. */
   readonly PlatformContent: "platform.content";
+  /** Feature flags team. */
   readonly PlatformFeatureFlags: "platform.featureflags";
+  /** Finance/billing team. */
   readonly PlatformFinance: "platform.finance";
 };
+/**
+ * Owner identifier for a spec.
+ * Can be a predefined OwnersEnum value or any custom string.
+ */
 type Owner = (typeof OwnersEnum)[keyof typeof OwnersEnum] | (string & {});
+/**
+ * Common tags for categorizing specs.
+ *
+ * Used for search, grouping, and documentation navigation.
+ * Custom tag strings are also allowed for flexibility.
+ */
 declare const TagsEnum: {
+  /** Spots/locations domain. */
   readonly Spots: "spots";
+  /** Collectivity/community domain. */
   readonly Collectivity: "collectivity";
+  /** Marketplace domain. */
   readonly Marketplace: "marketplace";
+  /** Seller-related features. */
   readonly Sellers: "sellers";
+  /** Authentication features. */
   readonly Auth: "auth";
+  /** Login flows. */
   readonly Login: "login";
+  /** Signup flows. */
   readonly Signup: "signup";
+  /** Onboarding/guides. */
   readonly Guide: "guide";
+  /** Documentation. */
   readonly Docs: "docs";
+  /** Internationalization. */
   readonly I18n: "i18n";
+  /** Incident management. */
   readonly Incident: "incident";
+  /** Automation/workflows. */
   readonly Automation: "automation";
+  /** Code hygiene/maintenance. */
   readonly Hygiene: "hygiene";
 };
+/**
+ * Tag for categorizing a spec.
+ * Can be a predefined TagsEnum value or any custom string.
+ */
 type Tag = (typeof TagsEnum)[keyof typeof TagsEnum] | (string & {});
+/**
+ * Common metadata interface for all ContractSpec specifications.
+ *
+ * Every spec type (operations, events, presentations, etc.) extends this
+ * interface to provide consistent ownership, versioning, and discoverability.
+ *
+ * @example
+ * ```typescript
+ * const meta: OwnerShipMeta = {
+ *   key: 'auth.login',
+ *   version: '1.0.0',
+ *   description: 'Authenticates a user with email and password',
+ *   stability: StabilityEnum.Stable,
+ *   owners: [OwnersEnum.PlatformSigil],
+ *   tags: [TagsEnum.Auth, TagsEnum.Login],
+ * };
+ * ```
+ */
 interface OwnerShipMeta {
-  /** Breaking changes => bump version */
+  /**
+   * Semantic version string (e.g., "1.0.0").
+   * Bump for breaking changes according to semver rules.
+   */
   version: string;
-  /** Fully-qualified spec key (e.g., "sigil.beginSignup") */
+  /**
+   * Fully-qualified spec key (e.g., "sigil.beginSignup", "user.created").
+   * Must be unique within the spec type.
+   */
   key: string;
-  /** Human-friendly spec title (e.g., "Signup begin") */
+  /**
+   * Human-friendly title (e.g., "Begin Signup").
+   * Used in documentation and UI.
+   */
   title?: string;
-  /** Short human-friendly summary */
+  /**
+   * Short human-friendly summary of what this spec does.
+   * Should be concise (1-2 sentences).
+   */
   description: string;
+  /**
+   * Business domain this spec belongs to (e.g., "auth", "marketplace").
+   * Used for grouping and discovery.
+   */
   domain?: string;
-  /** Lifecycle marker for comms & tooling */
+  /**
+   * Lifecycle stability marker.
+   * Indicates maturity level and change expectations.
+   */
   stability: Stability;
-  /** Owners for CODEOWNERS / on-call / approvals */
+  /**
+   * Team/individual owners responsible for this spec.
+   * Used for CODEOWNERS, on-call routing, and approvals.
+   */
   owners: Owner[];
-  /** Search tags, grouping, docs navigation */
+  /**
+   * Tags for search, grouping, and documentation navigation.
+   */
   tags: Tag[];
-  /** Doc block(s) for this operation. */
+  /**
+   * Associated DocBlock identifiers for documentation linkage.
+   */
   docId?: DocId[];
 }
 //#endregion

package/dist/contracts/src/ownership.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ownership.d.ts","names":[],"sources":["../../../../contracts/src/ownership.ts"],"sourcesContent":[],"mappings":";;;;cAIa;;;EAAA,SAAA,YAOH,EAAA,cAAA;EACE,SAAA,IAAS,EAAA,MAAA;EAGR,SAAA,MAQH,EAAA,QAAA;EACE,SAAK,UAAA,EACL,YAAyB;AAMrC,CAAA;AAeY,KAlCA,SAAA,GAkCc,CAAA,OAlCM,aAkCyB,CAAA,CAAA,MAAA,OAlCG,aAkCH,CAAA;AAIxC,cAnCJ,UAmCiB,EAAA;EAWjB,SAAA,YAAA,EAAA,eAAA;EAEH,SAAA,aAAA,EAAA,gBAAA;EAEF,SAAA,mBAAA,EAAA,sBAAA;EAGE,SAAA,iBAAA,EAAA,oBAAA;EAAK,SAAA,eAAA,EAAA,kBAAA;;;;KA5CH,KAAA,WACA,yBAAyB;cAMxB;;;;;;;;;;;;;;;KAeD,GAAA,WAAc,uBAAuB;UAIhC,aAAA;;;;;;;;;;;aAWJ;;UAEH;;QAEF;;UAGE"}
+{"version":3,"file":"ownership.d.ts","names":[],"sources":["../../../../contracts/src/ownership.ts"],"sourcesContent":[],"mappings":";;;;;AA6HA;AA2BA;;;;;;;;;;cA9Ha;;;;;;;;;;;;;;;KAgBD,SAAA,WAAoB,4BAA4B;;;;;;;cAY/C;;;;;;;;;;;;;;;;;;;;KAqBD,KAAA,WACA,yBAAyB;;;;;;;cAgBxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAiCD,GAAA,WAAc,uBAAuB;;;;;;;;;;;;;;;;;;;UA2BhC,aAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aAmCJ;;;;;UAMH;;;;QAKF;;;;UAKE"}

package/dist/contracts/src/policy/spec.d.ts

@@ -1,11 +1,13 @@
 import "../ownership.js";
+import { VersionedSpecRef } from "../versioning/refs.js";
 
 //#region ../contracts/src/policy/spec.d.ts
 
-interface PolicyRef {
-  key: string;
-  version: string;
-}
+/**
+ * Reference to a policy spec.
+ * Uses key and version to identify a specific policy.
+ */
+type PolicyRef = VersionedSpecRef;
 //#endregion
 export { PolicyRef };
 //# sourceMappingURL=spec.d.ts.map

package/dist/contracts/src/policy/spec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"spec.d.ts","names":[],"sources":["../../../../../contracts/src/policy/spec.ts"],"sourcesContent":[],"mappings":";;;;UAmHiB,SAAA"}
+{"version":3,"file":"spec.d.ts","names":[],"sources":["../../../../../contracts/src/policy/spec.ts"],"sourcesContent":[],"mappings":";;;;;;;;;KAyHY,SAAA,GAAY"}

package/dist/contracts/src/serialization/index.d.ts

@@ -0,0 +1 @@
+import "./serializers.js";

package/dist/contracts/src/serialization/serializers.d.ts

@@ -0,0 +1,7 @@
+import "../../../schema/src/index.js";
+import "../resources.js";
+import "../operations/index.js";
+import "../presentations/index.js";
+import "../data-views/index.js";
+import "../events.js";
+import "../forms/index.js";

package/dist/contracts/src/tests/spec.d.ts

@@ -1,11 +1,13 @@
 import "../ownership.js";
+import { OptionalVersionedSpecRef } from "../versioning/refs.js";
 
 //#region ../contracts/src/tests/spec.d.ts
 
-interface TestSpecRef {
-  key: string;
-  version?: string;
-}
+/**
+ * Reference to a test spec.
+ * Version is optional; when omitted, refers to the latest version.
+ */
+type TestSpecRef = OptionalVersionedSpecRef;
 //#endregion
 export { TestSpecRef };
 //# sourceMappingURL=spec.d.ts.map

package/dist/contracts/src/tests/spec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"spec.d.ts","names":[],"sources":["../../../../../contracts/src/tests/spec.ts"],"sourcesContent":[],"mappings":";;;;UAiFiB,WAAA"}
+{"version":3,"file":"spec.d.ts","names":[],"sources":["../../../../../contracts/src/tests/spec.ts"],"sourcesContent":[],"mappings":";;;;;;;;;KAwFY,WAAA,GAAc"}

package/dist/contracts/src/versioning/refs.d.ts

@@ -0,0 +1,47 @@
+//#region ../contracts/src/versioning/refs.d.ts
+/**
+ * Base reference types for ContractSpec versioning.
+ *
+ * Provides canonical reference types for linking between specs.
+ * Domain-specific refs (OpRef, EventRef, etc.) should alias these
+ * base types for consistency and maintainability.
+ *
+ * @module versioning/refs
+ */
+/**
+ * Base reference type for versioned specs.
+ * Used to reference any spec by its key and version.
+ *
+ * @example
+ * ```typescript
+ * const opRef: VersionedSpecRef = { key: 'auth.login', version: '1.0.0' };
+ * ```
+ */
+interface VersionedSpecRef {
+  /** Unique key identifying the spec (e.g., "auth.login", "user.created"). */
+  key: string;
+  /** Semantic version of the spec (e.g., "1.0.0", "2.1.0"). */
+  version: string;
+}
+/**
+ * Base reference type for specs with optional version.
+ * When version is omitted, typically refers to the latest version.
+ *
+ * @example
+ * ```typescript
+ * // Reference to latest version
+ * const latestRef: OptionalVersionedSpecRef = { key: 'auth.login' };
+ *
+ * // Reference to specific version
+ * const specificRef: OptionalVersionedSpecRef = { key: 'auth.login', version: '1.0.0' };
+ * ```
+ */
+interface OptionalVersionedSpecRef {
+  /** Unique key identifying the spec. */
+  key: string;
+  /** Optional semantic version. When omitted, refers to the latest version. */
+  version?: string;
+}
+//#endregion
+export { OptionalVersionedSpecRef, VersionedSpecRef };
+//# sourceMappingURL=refs.d.ts.map

package/dist/contracts/src/versioning/refs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refs.d.ts","names":[],"sources":["../../../../../contracts/src/versioning/refs.ts"],"sourcesContent":[],"mappings":";;AAuBA;AAoBA;;;;;;;;;;;;;;;;UApBiB,gBAAA;;;;;;;;;;;;;;;;;;;UAoBA,wBAAA"}

package/dist/contracts/src/workflow/index.d.ts

@@ -1,3 +1,4 @@
+import { FormRef } from "../features/types.js";
 import "./spec.js";
 import "./validation.js";
 import "./state.js";

package/dist/contracts/src/workflow/spec.d.ts

@@ -1,5 +1,6 @@
 import "../ownership.js";
 import "../capabilities/index.js";
 import "../experiments/spec.js";
+import { FormRef } from "../features/types.js";
 import "../features/index.js";
 import "../registry.js";

package/dist/schema/src/FieldType.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FieldType.d.ts","names":[],"sources":["../../../../schema/src/FieldType.ts"],"sourcesContent":[],"mappings":";;;;UAGiB,uCAEH,mBACJ,wBAAwB,WAAW;OACtC,CAAA,CAAE,QAAQ;EAJA,UAAA,EAAA,OAAe,GAAA,CAAA,GAAA,GAAA,OAAA,CAAA;;AAGE,KAMtB,YAAA,GAAe,SANO,CAAA,GAAA,EAAA,GAAA,CAAA;;;;;;AAMtB,cAOC,SAPW,CAAA,SAAG,EAAS,YAStB,SATsB,CAAA,SAU1B,iBAV0B,CAUR,SAVQ,EAUG,SAVH,CAAA,CAAA;EAOvB,QAAA,SAAS;EAER,iBAAA,aAAA;EACc,WAAA,CAAA,MAAA,EAIN,eAJM,CAIU,SAJV,EAIqB,SAJrB,CAAA;EAAW;EAID,MAAA,CAAA,CAAA,EAO1B,CAAA,CAAE,OAPwB,CAOhB,SAPgB,CAAA;EAAW;EAA3B,SAAA,CAAA,CAAA,EAYP,iBAZO,CAYW,SAZX,EAYsB,SAZtB,CAAA;EAOA;EAAR,OAAA,CAAA,CAAA,EAAA,OAAA;EAKmB,gBAAA,CAAA,CAAA,EAAA,OAAA,GAAA,CAAA,GAAA,GAAA,OAAA,CAAA;EAAW,aAAA,CAAA,CAAA,EAAA,OAAA"}
+{"version":3,"file":"FieldType.d.ts","names":[],"sources":["../../../../schema/src/FieldType.ts"],"sourcesContent":[],"mappings":";;;;UAGiB,uCAEH,mBACJ,wBAAwB,WAAW;OACtC,CAAA,CAAE,QAAQ;EAJA,UAAA,EAAA,OAAe,GAAA,CAAA,GAAA,GAAA,OAAA,CAAA;;AAGE,KAMtB,YAAA,GAAe,SANO,CAAA,GAAA,EAAA,GAAA,CAAA;;;;;;AAMtB,cAOC,SAPW,CAAG,SAAA,EAAS,YAStB,SATsB,CAAA,SAU1B,iBAV0B,CAUR,SAVQ,EAUG,SAVH,CAAA,CAAA;EAOvB,QAAA,SAAS;EAER,iBAAA,aAAA;EACc,WAAA,CAAA,MAAA,EAIN,eAJM,CAIU,SAJV,EAIqB,SAJrB,CAAA;EAAW;EAID,MAAA,CAAA,CAAA,EAO1B,CAAA,CAAE,OAPwB,CAOhB,SAPgB,CAAA;EAAW;EAA3B,SAAA,CAAA,CAAA,EAYP,iBAZO,CAYW,SAZX,EAYsB,SAZtB,CAAA;EAOA;EAAR,OAAA,CAAA,CAAA,EAAA,OAAA;EAKmB,gBAAA,CAAA,CAAA,EAAA,OAAA,GAAA,CAAA,GAAA,GAAA,OAAA,CAAA;EAAW,aAAA,CAAA,CAAA,EAAA,OAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contractspec/lib.feature-flags",
-  "version": "1.48.1",
+  "version": "1.50.0",
   "description": "Feature flags and experiments module for ContractSpec applications",
   "keywords": [
     "contractspec",
@@ -24,13 +24,13 @@
     "lint:check": "eslint src"
   },
   "dependencies": {
-    "@contractspec/lib.schema": "1.48.0",
-    "@contractspec/lib.contracts": "1.48.1",
+    "@contractspec/lib.schema": "1.50.0",
+    "@contractspec/lib.contracts": "1.50.0",
     "zod": "^4.3.5"
   },
   "devDependencies": {
-    "@contractspec/tool.typescript": "1.48.0",
-    "@contractspec/tool.tsdown": "1.48.0",
+    "@contractspec/tool.typescript": "1.50.0",
+    "@contractspec/tool.tsdown": "1.50.0",
     "typescript": "^5.9.3"
   },
   "exports": {