@contractspec/example.personalization 1.48.1 → 1.50.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @contractspec/example.personalization
 
+## 1.50.0
+
+### Minor Changes
+
+- 5325d6b: feat: improve seo
+
+### Patch Changes
+
+- Updated dependencies [5325d6b]
+  - @contractspec/lib.contracts@1.50.0
+  - @contractspec/lib.logger@1.50.0
+  - @contractspec/lib.overlay-engine@1.50.0
+  - @contractspec/lib.personalization@1.50.0
+  - @contractspec/lib.workflow-composer@1.50.0
+
+## 1.49.0
+
+### Minor Changes
+
+- cafd041: fix: impact report comments within github action
+
+### Patch Changes
+
+- Updated dependencies [cafd041]
+  - @contractspec/lib.workflow-composer@1.49.0
+  - @contractspec/lib.personalization@1.49.0
+  - @contractspec/lib.overlay-engine@1.49.0
+  - @contractspec/lib.contracts@1.49.0
+  - @contractspec/lib.logger@1.49.0
+
 ## 1.48.1
 
 ### Patch Changes

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

@@ -1,16 +1,29 @@
+import { VersionedSpecRef } from "../versioning/refs.js";
+
 //#region ../../libs/contracts/src/capabilities/capabilities.d.ts
+/** Classification of capability types. */
 type CapabilityKind = 'api' | 'event' | 'data' | 'ui' | 'integration';
+/**
+ * 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;
 //#endregion
 export { CapabilityKind, CapabilityRef, CapabilityRequirement };
 //# sourceMappingURL=capabilities.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"capabilities.d.ts","names":[],"sources":["../../../../../../../libs/contracts/src/capabilities/capabilities.ts"],"sourcesContent":[],"mappings":";AAGY,KAAA,cAAA,GAAc,KAAA,GAAA,OAAA,GAAA,MAAA,GAAA,IAAA,GAAA,aAAA;UAoBT,qBAAA;;;SAGR;;;;UAKQ,aAAA"}
+{"version":3,"file":"capabilities.d.ts","names":[],"sources":["../../../../../../../libs/contracts/src/capabilities/capabilities.ts"],"sourcesContent":[],"mappings":";;;;AAKY,KAAA,cAAA,GAAc,KAAA,GAAA,OAAA,GAAA,MAAA,GAAA,IAAA,GAAA,aAAA;;;;;UAmCT,qBAAA;;;;;;SAMR;;;;;;;;;;KAWG,aAAA,GAAgB"}

package/dist/libs/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/libs/contracts/src/data-views/spec.d.ts

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

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

@@ -1,11 +1,13 @@
+import { OptionalVersionedSpecRef } from "../versioning/refs.js";
 import "../registry.js";
 
 //#region ../../libs/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/libs/contracts/src/experiments/spec.d.ts.map

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

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

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

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

@@ -1,5 +1,6 @@
 import { PresentationTarget } from "../presentations/presentations.js";
 import { OwnerShipMeta } from "../ownership.js";
+import { SpecKeyRef, VersionedSpecRef } from "../versioning/refs.js";
 import { CapabilityRef, CapabilityRequirement } from "../capabilities/capabilities.js";
 import { ExperimentRef } from "../experiments/spec.js";
 import { ImplementationRef } from "../operations/operation.js";
@@ -8,38 +9,31 @@ import "../operations/index.js";
 //#region ../../libs/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;
@@ -80,9 +74,11 @@ interface FeatureModuleSpec {
   /** Forms associated with this feature. */
   forms?: FormRef[];
 }
-interface FeatureRef {
-  key: string;
-}
+/**
+ * Reference to a feature (unversioned).
+ * Features are identified by key only, without version pinning.
+ */
+type FeatureRef = SpecKeyRef;
 //#endregion
-export { EventRef, FeatureModuleMeta, FeatureModuleSpec, FeatureRef, OpRef, PresentationRef };
+export { DataViewRef, EventRef, FeatureModuleMeta, FeatureModuleSpec, FeatureRef, FormRef, OpRef, PresentationRef };
 //# sourceMappingURL=types.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","names":[],"sources":["../../../../../../../libs/contracts/src/features/types.ts"],"sourcesContent":[],"mappings":";;;;;;;;;KAOY,iBAAA,GAAoB;UAEf,KAAA;EAFL;EAEK,GAAA,EAAA,MAAK;EAOL;EAOA,OAAA,EAAA,MAAA;AAUjB;AAQiB,UAzBA,QAAA,CAyBO;EAMP;EACT,GAAA,EAAA,MAAA;EAEO;EAEJ,OAAA,EAAA,MAAA;;AAIK,UAjCC,eAAA,CAiCD;EAGD;EACA,GAAA,EAAA,MAAA;EAGY;EAAa,OAAA,EAAA,MAAA;;;;;AAqBvB,UAnDA,WAAA,CAmDA;EAGA,GAAA,EAAA,MAAA;;;;;;UA9CA,OAAA;;;;;UAMA,iBAAA;QACT;;eAEO;;WAEJ;;kBAEO;;gBAEF;;;eAGD;eACA;;;;QAGY;UAAa;;;;;;;;;aAQ3B;;;;;;oBAOO;;cAGN;;UAGJ;;UAGO,UAAA"}
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../../../../../../libs/contracts/src/features/types.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;KAQY,iBAAA,GAAoB;;AAAhC;AAMA;AAMA;AAMY,KAZA,KAAA,GAAQ,gBAYU;AAM9B;AAMA;AAGA;;AAGe,KAxBH,QAAA,GAAW,gBAwBR;;;;;AAUA,KA5BH,eAAA,GAAkB,gBA4Bf;;;;;AAqBD,KA3CF,WAAA,GAAc,gBA2CZ;;;AAUd;;KA/CY,OAAA,GAAU;;UAGL,iBAAA;QACT;;eAEO;;WAEJ;;kBAEO;;gBAEF;;;eAGD;eACA;;;;QAGY;UAAa;;;;;;;;;aAQ3B;;;;;;oBAOO;;cAGN;;UAGJ;;;;;;KAOE,UAAA,GAAa"}

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

@@ -1,6 +1,7 @@
 import { PresentationTarget } from "./presentations/presentations.js";
 import { DocId } from "./docs/registry.js";
 import { Owner, OwnerShipMeta, OwnersEnum, Stability, StabilityEnum, Tag, TagsEnum } from "./ownership.js";
+import { OptionalVersionedSpecRef, SpecKeyRef, VersionedSpecRef } from "./versioning/refs.js";
 import { PolicyRef } from "./policy/spec.js";
 import { CapabilityKind, CapabilityRef, CapabilityRequirement } from "./capabilities/capabilities.js";
 import { ExperimentRef } from "./experiments/spec.js";
@@ -8,11 +9,11 @@ import "./resources.js";
 import { ImplementationRef, ImplementationType } from "./operations/operation.js";
 import "./install.js";
 import "./operations/index.js";
-import { EventRef, FeatureModuleMeta, FeatureModuleSpec, FeatureRef, OpRef, PresentationRef } from "./features/types.js";
+import { DataViewRef, EventRef, FeatureModuleMeta, FeatureModuleSpec, FeatureRef, FormRef, OpRef, PresentationRef } from "./features/types.js";
 import "./presentations/index.js";
 import "./features/index.js";
 import "./data-views/index.js";
-import { CompensationStep, CompensationStrategy, FormRef, GuardCondition, GuardConditionKind, RetryPolicy, SLA, Step, StepAction, StepType, Transition, WorkflowDefinition, WorkflowMeta, WorkflowSpec } from "./workflow/spec.js";
+import { CompensationStep, CompensationStrategy, GuardCondition, GuardConditionKind, RetryPolicy, SLA, Step, StepAction, StepType, Transition, WorkflowDefinition, WorkflowMeta, WorkflowSpec } from "./workflow/spec.js";
 import { ThemeRef } from "./themes.js";
 import { IntegrationCategory, IntegrationOwnershipMode } from "./integrations/spec.js";
 import { AppBlueprintMeta, AppBlueprintSpec, AppIntegrationSlot, AppRouteConfig, AppThemeBinding, FeatureFlagState, SpecPointer, TelemetryBinding, TranslationCatalogPointer } from "./app-config/spec.js";
@@ -40,4 +41,5 @@ import "./workflow/index.js";
 import "./llm/index.js";
 import "./app-config/validation.js";
 import { ExampleDocumentation, ExampleEntrypoints, ExampleKind, ExampleMcpSupport, ExampleMeta, ExampleSandboxMode, ExampleSandboxSupport, ExampleSpec, ExampleStudioSupport, ExampleSurfaces, ExampleVisibility } from "./examples/types.js";
-import "./examples/index.js";
+import "./examples/index.js";
+import "./serialization/index.js";

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

@@ -1,58 +1,161 @@
 import { DocId } from "./docs/registry.js";
 
 //#region ../../libs/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/libs/contracts/src/ownership.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ownership.d.ts","names":[],"sources":["../../../../../../libs/contracts/src/ownership.ts"],"sourcesContent":[],"mappings":";;;cAIa;;EAAA,SAAA,UAOH,EAAA,aAAA;EACE,SAAA,YAAS,EAAA,cAAW;EAGnB,SAAA,IAQH,EAAA,MAAA;EACE,SAAK,MAAA,EAAA,QACL;EAMC,SAAA,UAcH,EAAA,YAAA;AACV,CAAA;AAIiB,KAtCL,SAAA,GAsCkB,CAAA,OAtCE,aAsCF,CAAA,CAAA,MAAA,OAtC8B,aAsC9B,CAAA;AAWjB,cA9CA,UA8CA,EAAA;EAEH,SAAA,YAAA,EAAA,eAAA;EAEF,SAAA,aAAA,EAAA,gBAAA;EAGE,SAAA,mBAAA,EAAA,sBAAA;EAAK,SAAA,iBAAA,EAAA,oBAAA;;;;;KA5CH,KAAA,WACA,yBAAyB;cAMxB;;;;;;;;;;;;;;;KAeD,GAAA,WAAc,uBAAuB;UAIhC,aAAA;;;;;;;;;;;aAWJ;;UAEH;;QAEF;;UAGE"}
+{"version":3,"file":"ownership.d.ts","names":[],"sources":["../../../../../../libs/contracts/src/ownership.ts"],"sourcesContent":[],"mappings":";;;;AAwJA;;;;;;;;;;;cA9Ha;;;;;;;;;;;;;;;KAgBD,SAAA,WAAoB,4BAA4B;;;;;;;cAY/C;;;;;;;;;;;;;;;;;;;;KAqBD,KAAA,WACA,yBAAyB;;;;;;;cAgBxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAiCD,GAAA,WAAc,uBAAuB;;;;;;;;;;;;;;;;;;;UA2BhC,aAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aAmCJ;;;;;UAMH;;;;QAKF;;;;UAKE"}

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

@@ -1,9 +1,12 @@
+import { VersionedSpecRef } from "../versioning/refs.js";
+
 //#region ../../libs/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/libs/contracts/src/policy/spec.d.ts.map

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

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

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

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

@@ -0,0 +1,5 @@
+import "../resources.js";
+import "../operations/index.js";
+import "../presentations/index.js";
+import "../data-views/index.js";
+import "../events.js";

package/dist/libs/contracts/src/themes.d.ts

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

package/dist/libs/contracts/src/themes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"themes.d.ts","names":[],"sources":["../../../../../../libs/contracts/src/themes.ts"],"sourcesContent":[],"mappings":";;;;UAgDiB,QAAA"}
+{"version":3,"file":"themes.d.ts","names":[],"sources":["../../../../../../libs/contracts/src/themes.ts"],"sourcesContent":[],"mappings":";;;;;;;;;KAsDY,QAAA,GAAW"}

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

@@ -0,0 +1,60 @@
+//#region ../../libs/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;
+}
+/**
+ * Base reference type for unversioned spec keys.
+ * Used when only the key is needed without version information.
+ *
+ * @example
+ * ```typescript
+ * const featureRef: SpecKeyRef = { key: 'premium-features' };
+ * ```
+ */
+interface SpecKeyRef {
+  /** Unique key identifying the spec. */
+  key: string;
+}
+//#endregion
+export { OptionalVersionedSpecRef, SpecKeyRef, VersionedSpecRef };
+//# sourceMappingURL=refs.d.ts.map

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

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

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

@@ -1,4 +1,5 @@
-import { CompensationStep, CompensationStrategy, FormRef, GuardCondition, GuardConditionKind, RetryPolicy, SLA, Step, StepAction, StepType, Transition, WorkflowDefinition, WorkflowMeta, WorkflowSpec } from "./spec.js";
+import { FormRef } from "../features/types.js";
+import { CompensationStep, CompensationStrategy, GuardCondition, GuardConditionKind, RetryPolicy, SLA, Step, StepAction, StepType, Transition, WorkflowDefinition, WorkflowMeta, WorkflowSpec } from "./spec.js";
 import "./validation.js";
 import "./state.js";
 import "./runner.js";

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

@@ -1,18 +1,11 @@
 import { OwnerShipMeta } from "../ownership.js";
 import { CapabilityRef } from "../capabilities/capabilities.js";
 import { ExperimentRef } from "../experiments/spec.js";
-import { OpRef } from "../features/types.js";
+import { FormRef, OpRef } from "../features/types.js";
 import "../features/index.js";
 import "../registry.js";
 
 //#region ../../libs/contracts/src/workflow/spec.d.ts
-/**
- * Reference to a form spec declared in {@link FormRegistry}.
- */
-interface FormRef {
-  key: string;
-  version: string;
-}
 type StepType = 'human' | 'automation' | 'decision';
 type GuardConditionKind = 'policy' | 'expression';
 interface GuardCondition {
@@ -85,5 +78,5 @@ interface WorkflowSpec {
   experiments?: ExperimentRef[];
 }
 //#endregion
-export { CompensationStep, CompensationStrategy, FormRef, GuardCondition, GuardConditionKind, RetryPolicy, SLA, Step, StepAction, StepType, Transition, WorkflowDefinition, WorkflowMeta, WorkflowSpec };
+export { CompensationStep, CompensationStrategy, GuardCondition, GuardConditionKind, RetryPolicy, SLA, Step, StepAction, StepType, Transition, WorkflowDefinition, WorkflowMeta, WorkflowSpec };
 //# sourceMappingURL=spec.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"spec.d.ts","names":[],"sources":["../../../../../../../libs/contracts/src/workflow/spec.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;AASiB,UAAA,OAAA,CAAO;EAKZ,GAAA,EAAA,MAAQ;EASR,OAAA,EAAA,MAAA;AAEZ;AAMiB,KAjBL,QAAA,GAiBgB,OAAA,GAAA,YAAA,GAAA,UAAA;AAeX,KAvBL,kBAAA,GAuBS,QAAA,GAAA,YAAA;AAEb,UAvBS,cAAA,CAuBT;EAGG,IAAA,EAzBH,kBAyBG;EACD;EAEA,KAAA,EAAA,MAAA;;AAI4B,UA3BrB,WAAA,CA2BqB;EAGrB,WAAA,EAAU,MAAA;EAQV,OAAG,EAAA,QAAA,GAED,aAAM;EAGR,OAAA,EAAA,MAAA;EAMA;EAKA,UAAA,CAAA,EAAA,MAAA;;AAEF,UAhDE,UAAA,CAgDF;EAGP;EACS,SAAA,CAAA,EAlDH,KAkDG;EAAoB;EAGzB,IAAA,CAAA,EAnDH,OAmDG;AAEZ;AACQ,UAnDS,IAAA,CAmDT;EACM,EAAA,EAAA,MAAA;EAEE,IAAA,EApDR,QAoDQ;EAAa,KAAA,EAAA,MAAA;;WAjDlB;UACD;;UAEA;;;;yBAIe;;UAGR,UAAA;;;;;;;UAQA,GAAA;;mBAEE;;UAGF,gBAAA;;aAEJ;;;UAII,oBAAA;;SAER;;UAGQ,kBAAA;SACR;eACM;;;QAGP;iBACS;;KAGL,YAAA,GAAe;UAEV,YAAA;QACT;cACM;;;;gBAEE"}
+{"version":3,"file":"spec.d.ts","names":[],"sources":["../../../../../../../libs/contracts/src/workflow/spec.ts"],"sourcesContent":[],"mappings":";;;;;;;;KASY,QAAA;AAAA,KASA,kBAAA,GATQ,QAAA,GAAA,YAAA;AASR,UAEK,cAAA,CAFa;EAEb,IAAA,EACT,kBADuB;EAMd;EAQA,KAAA,EAAA,MAAU;AAO3B;AAEQ,UAjBS,WAAA,CAiBT;EAGG,WAAA,EAAA,MAAA;EACD,OAAA,EAAA,QAAA,GAAA,aAAA;EAEA,OAAA,EAAA,MAAA;EAIe;EAAa,UAAA,CAAA,EAAA,MAAA;AAGtC;AAQiB,UA9BA,UAAA,CAgCE;EAGF;EAMA,SAAA,CAAA,EAvCH,KAuCG;EAKA;EACR,IAAA,CAAA,EA3CA,OA2CA;;AAID,UA5CS,IAAA,CA4CT;EACS,EAAA,EAAA,MAAA;EAAoB,IAAA,EA3C7B,QA2C6B;EAGzB,KAAA,EAAA,MAAA;EAEK,WAAA,CAAA,EAAA,MAAY;EACrB,MAAA,CAAA,EA9CG,UA8CH;EACM,KAAA,CAAA,EA9CJ,cA8CI;EAEE,SAAA,CAAA,EAAA,MAAA;EAAa,KAAA,CAAA,EA9CnB,WA8CmB;;;;yBA1CJ;;UAGR,UAAA;;;;;;;UAQA,GAAA;;mBAEE;;UAGF,gBAAA;;aAEJ;;;UAII,oBAAA;;SAER;;UAGQ,kBAAA;SACR;eACM;;;QAGP;iBACS;;KAGL,YAAA,GAAe;UAEV,YAAA;QACT;cACM;;;;gBAEE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contractspec/example.personalization",
-  "version": "1.48.1",
+  "version": "1.50.0",
   "description": "Personalization examples: behavior tracking, overlay customization, workflow extension.",
   "type": "module",
   "types": "./dist/index.d.ts",
@@ -28,15 +28,15 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@contractspec/lib.personalization": "1.48.1",
-    "@contractspec/lib.overlay-engine": "1.48.1",
-    "@contractspec/lib.workflow-composer": "1.48.1",
-    "@contractspec/lib.contracts": "1.48.1",
-    "@contractspec/lib.logger": "1.48.0"
+    "@contractspec/lib.personalization": "1.50.0",
+    "@contractspec/lib.overlay-engine": "1.50.0",
+    "@contractspec/lib.workflow-composer": "1.50.0",
+    "@contractspec/lib.contracts": "1.50.0",
+    "@contractspec/lib.logger": "1.50.0"
   },
   "devDependencies": {
-    "@contractspec/tool.tsdown": "1.48.0",
-    "@contractspec/tool.typescript": "1.48.0",
+    "@contractspec/tool.tsdown": "1.50.0",
+    "@contractspec/tool.typescript": "1.50.0",
     "tsdown": "^0.19.0",
     "typescript": "^5.9.3"
   },